---
title: Bucket Atlas
emoji: 🗺️
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# Bucket Atlas

Explore Florence with MapLibre and PMTiles, served from a private Hugging Face bucket through Bun's S3 client. Pan around the city, visit landmarks, change map layers, inspect buildings, and see how many archive bytes the browser reads.

## Storage configuration

The initial Space and bucket are private. Set these **Space secrets**:

- `HF_S3_ACCESS_KEY_ID`
- `HF_S3_SECRET_ACCESS_KEY`

Use a credential with read access to `cfahlgren1/bucket-atlas`. S3 requires both values. An access-key ID by itself is insufficient. No HF token or S3 secret is sent to the browser.

Optional Space variables default to:

```text
HF_S3_NAMESPACE=cfahlgren1
HF_S3_BUCKET=bucket-atlas
PMTILES_KEY=maps/florence.pmtiles
```

The app serves only the configured archive through `/maps/florence.pmtiles`. The Bun server signs an S3 request, verifies the upstream returns the requested range, and streams the bytes to the browser. A single request is limited to 8 MiB. Requests for full archives and multiple ranges are rejected. Responses use private, no-store caching. The browser still caches PMTiles directory and tile data in memory.

Viewer access is provided by the private Space. Making the Space public makes the selected map readable through the app, even though the bucket itself remains private.

## Local development

```sh
bun install --frozen-lockfile
bun run build
# Use the S3 secrets from your environment:
bun start
```

For explicit local development, download the sample and set `LOCAL_PMTILES`:

```sh
mkdir -p data
curl -fL 'https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles' -o data/florence.pmtiles
LOCAL_PMTILES=data/florence.pmtiles bun start
bun test
bun run check
```

The local archive is not included in the Docker image. There is no automatic local fallback in the deployed Space. Without valid S3 credentials, the UI reports that storage needs setup.

## Map data and credits

The [Protomaps Florence sample](https://github.com/protomaps/PMTiles/blob/main/js/examples/maplibre.html) contains a regional OpenStreetMap basemap snapshot from August 2024. It is 6,601,156 bytes, with native zoom levels through 15. Higher display zooms reuse those tiles. It covers central Florence, not all of Tuscany. Building heights use the source value when present and a 7 m visual default otherwise.

Map data © OpenStreetMap contributors, distributed under ODbL. [OpenStreetMap copyright and license](https://www.openstreetmap.org/copyright). Tiles distributed by Protomaps. Fonts are loaded from Google Fonts and the Protomaps font assets host. The byte counter measures PMTiles response payloads only, not scripts, fonts, HTTP overhead, or total network traffic.

## Verification

`bun test` uses the real sample file and a real HTTP server. It verifies byte equality and headers, HEAD, invalid and multiple ranges, fixed-path access, PMTiles metadata parsing, and actual tile decoding. These tests use the local development backend; they do not prove live S3 credentials or HF gateway behavior.

The browser UI was also exercised locally, including navigation, popups and layer controls. The S3 deployment requires a final authenticated range/read and browser check once the Space secret is available.