Every configuration knob in BCycle Map flows through one of three mechanisms: aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/samgutentag/bcycle-map/llms.txt
Use this file to discover all available pages before exploring further.
VITE_* build-time variable baked into the frontend bundle, a runtime variable declared in a wrangler.toml [vars] block and injected into the Worker’s Env object, or a GitHub Actions secret that drives the compaction and deployment workflows. This page catalogues all of them in one place so you never have to grep across three config files to remember where something lives.
Frontend variables (.env.local)
These are read by Vite at build time via import.meta.env. They must be present before running npm run build:web or npm run dev:web. Copy .env.example to .env.local and fill in the values for your account.
Base URL of the deployed read-API Worker. All frontend Set this to the URL printed by
fetch calls in
src/web/lib/api.ts are prefixed with this value. When empty (the default),
the Vite dev server’s built-in proxy forwards /api/* to localhost:8787,
so local three-terminal development works without changing this variable.Production example:npx wrangler deploy --config wrangler.read-api.toml.
Leave it empty (or unset) when running against local Workers.Public development URL of the R2 bucket, used by the frontend for cold-path
reads of historical parquet partitions (Plan 2 /
/explore view). Captured
from the Cloudflare dashboard after enabling the Public Development URL
on the bcycle-map-archive bucket.Production example:The public R2 URL is only required once the
/explore (Kepler + DuckDB-WASM)
view is active. For the live map alone you can leave this empty.Worker runtime variables (wrangler.toml [vars])
These are declared in the [vars] section of wrangler.toml and are available as properties on the Worker’s Env object at runtime. They are not secret — they ship as plain text in the deployed Worker bundle. Use Cloudflare dashboard Secrets (not [vars]) for anything sensitive.
Optional URL pointing to an external
systems.json file. When set, the
Worker fetches the list of GBFS systems from that URL at startup instead
of using the systems.json bundled into the Worker at deploy time.Useful for hot-swapping the system list without redeploying. Leave empty
(the default) to use the embedded file — simpler and faster, with no
outbound fetch dependency.Example:Worker bindings (wrangler.toml [[kv_namespaces]] / [[r2_buckets]])
These are infrastructure bindings declared in the [[kv_namespaces]] and [[r2_buckets]] blocks of each wrangler*.toml file. Wrangler injects them into the Worker’s Env object automatically at deploy time — you never reference them in [vars] or as secrets. Both are defined in worker-configuration.d.ts.
The KV namespace that stores the latest GBFS snapshot and the intra-hour
buffer keys for every active system. Set by the See Cloudflare Setup for the full
provisioning walkthrough.
[[kv_namespaces]] block
in all three wrangler*.toml files using the id and preview_id
produced when you run:The R2 bucket (
bcycle-map-archive) that holds compacted parquet
partitions written by the hourly compaction workflow. Set by the
[[r2_buckets]] block in all three wrangler*.toml files. The bucket
must be created before deploying:Worker secrets (Cloudflare dashboard / wrangler secret put)
These values are sensitive and must not appear in wrangler.toml. Set them as encrypted Cloudflare Workers Secrets via the dashboard (Workers & Pages → your worker → Settings → Variables → Add secret) or the CLI. They are available on the Worker’s Env object at runtime exactly like [vars] entries, but are never included in the deployed bundle in plain text.
Optional. Powers the
/api/geocode proxy endpoint in the read-API Worker.
The key is stored server-side and never exposed to the web bundle —
the browser calls /api/geocode?q=… and the Worker forwards the request
to the Google Maps Geocoding API on its behalf.Without this key the endpoint returns an error and address-based geocoding
(used by the NearbyStationsSheet when browser geolocation is denied) is
disabled. The rest of the map functions normally.Optional. A GitHub personal access token (classic) or fine-grained token
with Issues: Write permission on the repository. Used exclusively by
the smoke Worker (
src/workers/smoke.ts) to file a GitHub Issue when a
GBFS normalization error is detected during the daily health check.If unset, the smoke Worker logs a warning and skips issue filing — the
rest of its health-check logic still runs. Omit this secret if you do not
want automated issue creation.Optional. The
owner/repo slug that GITHUB_TOKEN has access to. The
smoke Worker uses this to construct the Issues API URL. Must be set
together with GITHUB_TOKEN — if either is missing the smoke Worker
skips filing.Example value: samgutentag/bcycle-mapGitHub Actions secrets
The compaction workflow (compact.yml) and the Workers deployment workflow (deploy-workers.yml) each need a set of repository secrets. Add these in GitHub → Settings → Secrets and variables → Actions → New repository secret.
| Secret | Required by | Description |
|---|---|---|
CF_ACCOUNT_ID | both workflows | Your Cloudflare account ID. Run npx wrangler whoami to find it. |
CLOUDFLARE_API_TOKEN | deploy-workers.yml | API token with Workers Scripts: Edit permission. Used by all three worker-deploy jobs. |
CF_KV_API_TOKEN | compact.yml | API token with Workers KV Storage: Edit permission. Uses the “Edit Cloudflare Workers KV Storage” template in the dashboard. |
CF_KV_NAMESPACE_ID | compact.yml | Production KV namespace id captured in Step 2 of Cloudflare setup. |
R2_ACCESS_KEY_ID | compact.yml | Access key for an R2 API token scoped to Object Read & Write on bcycle-map-archive. |
R2_SECRET_ACCESS_KEY | compact.yml | Secret shown once when the R2 token is created. Save it immediately. |
R2_BUCKET | compact.yml | R2 bucket name. Typically bcycle-map-archive. |
Your Cloudflare account ID, used by both
deploy-workers.yml (as
CLOUDFLARE_ACCOUNT_ID) and compact.yml (as CF_ACCOUNT_ID). Retrieve
it with:An API token that allows Wrangler to deploy Worker scripts. When creating
the token in the Cloudflare dashboard (My Profile → API Tokens → Create
Token), use the “Edit Cloudflare Workers” template. This secret is
consumed by all three deploy jobs in
deploy-workers.yml.A separate API token scoped to Workers KV Storage: Edit. The compaction
script (
scripts/compact.ts) uses this to read the intra-hour KV buffer
and delete keys after sealing them into parquet. Use the “Edit Cloudflare
Workers KV Storage” template when creating it.The production KV namespace
id (not the preview ID). This is the id
value output by npx wrangler kv namespace create GBFS_KV and pasted into
the [[kv_namespaces]] block of all three wrangler*.toml files.The access key component of an R2 API token. Create it in the Cloudflare
dashboard under R2 → Manage API Tokens → Create API Token, choosing
Object Read & Write permission scoped to the
bcycle-map-archive
bucket.The corresponding secret key. Cloudflare displays it only once at token
creation time — copy it immediately.
The name of the R2 bucket. Unless you changed it during provisioning this
will be
bcycle-map-archive.Quick-reference summary
| Variable | Where it lives | Required? |
|---|---|---|
VITE_API_BASE | .env.local | Required for production builds |
VITE_R2_PUBLIC_URL | .env.local | Optional (Plan 2 only) |
SYSTEMS_JSON_URL | wrangler.toml [vars] | Optional |
GBFS_KV | wrangler.toml [[kv_namespaces]] | Required |
GBFS_R2 | wrangler.toml [[r2_buckets]] | Required |
GOOGLE_MAPS_API_KEY | CF Worker Secret (read-api) | Optional |
GITHUB_TOKEN | CF Worker Secret (smoke) | Optional |
GITHUB_REPO | CF Worker Secret (smoke) | Optional |
CF_ACCOUNT_ID | GitHub repo secret | Required |
CLOUDFLARE_API_TOKEN | GitHub repo secret | Required |
CF_KV_API_TOKEN | GitHub repo secret | Required |
CF_KV_NAMESPACE_ID | GitHub repo secret | Required |
R2_ACCESS_KEY_ID | GitHub repo secret | Required |
R2_SECRET_ACCESS_KEY | GitHub repo secret | Required |
R2_BUCKET | GitHub repo secret | Required |