Skip to content

Environment Variables

Every env var read by the backend or frontend. Sources: backend/env.example.local, scripts/dev/pull-secrets.sh (authoritative list of prod secrets pulled from GCP Secret Manager), backend/config/config.go, frontend/.env + .github/workflows/images.yml (web EXPO_PUBLIC_* build-args), and direct grep of frontend/utils/.

Backend

The backend uses a two-layer config: config.{env}.yaml for non-sensitive defaults, .env.{env} for secrets and overrides. Env vars listed here override the matching YAML value. See Configuration for layer precedence.

Variable Required? Default Purpose
ENV no local Selects which config.{env}.yaml and .env.{env} to load. Values: local, test, dev, prod (development normalizes to dev, production to prod). An unrecognized value fails startup.
CORS_ALLOWED_ORIGINS no from YAML Comma-separated browser origins allowed to call the API. Overrides server.allowed_origins. * is rejected outside local and test.
TRUSTED_PROXY_COUNT no from YAML Reverse-proxy hops in front of the server, for X-Forwarded-For parsing. Ignored when TRUSTED_PROXIES is set.
TRUSTED_PROXIES no from YAML Comma-separated CIDR blocks whose X-Forwarded-For header is believed. Replaces the YAML list (pod CIDR plus Cloudflare edge ranges in dev/prod).
ABUSE_VIOLATION_THRESHOLD no 5 Attack-pattern violations within the window before a client key is blocked.
ABUSE_VIOLATION_WINDOW no 10m Window the violations are counted in.
ABUSE_BLOCK_DURATIONS no 15m,1h,24h Block length per strike, comma-separated; the last entry is the cap.
ABUSE_ALLOWLIST no empty Comma-separated CIDRs never blocked, on top of Cloudflare's ranges and private addresses.
WORKER_AUTH_SECRET no empty HMAC key (32+ bytes) first-party Workers sign X-Tomoda-Worker-Auth with. Empty disables the bypass.
DB_HOST yes from YAML Postgres host.
DB_PORT yes from YAML Postgres port.
DB_USER yes from YAML Postgres user.
DB_PASSWORD yes — Postgres password.
DB_NAME yes from YAML Postgres database name.
DB_SSLMODE yes from YAML Postgres SSL mode (disable locally, verify-full in the cluster).
DB_SSLROOTCERT no — Path to the CA cert that signs the server certificate. Required for sslmode=verify-ca/verify-full; omitted from the DSN when empty.
REDIS_HOST yes from YAML Redis host.
REDIS_PORT yes from YAML Redis port.
REDIS_PASSWORD no (local) / yes (prod) — Redis password. Blank for local docker-compose.
JWT_SECRET yes — HMAC secret for signing JWTs. At least 32 bytes, enforced at startup. Generate with openssl rand -base64 32.
STORAGE_ACCESS_KEY_ID yes — R2/RustFS access key for object storage (S3 API).
STORAGE_SECRET_ACCESS_KEY yes — R2/RustFS secret key.
STORAGE_ENDPOINT no — S3 API endpoint: http://<lan-ip>:9000 for local RustFS, https://<account>.r2.cloudflarestorage.com when deployed.
STORAGE_BUCKET / STORAGE_REGION no from config.<env>.yaml Bucket and region overrides (region is auto for R2).
STORAGE_USE_PATH_STYLE no from yaml true for RustFS.
STORAGE_PUBLIC_URL no from yaml Public asset host (https://assets[-dev].tomoda.life).
ASSET_SIGNING_KEY deployed — HMAC key shared with the assets Worker for signed media URLs (set in dev and prod clusters). Unset in local dev, where URLs fall back to presigned GETs.
STRIPE_SECRET_KEY for billing — Stripe API key. Use sk_test_… locally.
STRIPE_WEBHOOK_SECRET for billing — Verifies the signature on Stripe webhook callbacks (whsec_…).
GOOGLE_CLIENT_ID for Google OAuth — Web OAuth client ID for Google Sign-In (accepted aud). May be comma-separated.
GOOGLE_IOS_CLIENT_ID for Google OAuth (iOS) — Native iOS client ID; accepted as a valid Google token aud.
GOOGLE_ANDROID_CLIENT_ID for Google OAuth (Android) — Native Android client ID; accepted as a valid Google token aud.
GOOGLE_CLIENT_SECRET for Google OAuth — OAuth client secret.
GOOGLE_PLACES_API_KEY for Places — Google Places API key. Used only for resolve escalations (caller-supplied place id, rich-detail enrichment); search and autocomplete are Photon-only.
APPLE_CLIENT_ID for Apple SIWA (iOS) — iOS bundle ID, e.g. com.tomoda.app.
APPLE_SERVICE_ID for Apple SIWA (web/Android) — Apple Services ID, e.g. com.tomoda.app.service.
APPLE_TEAM_ID for Apple SIWA — Apple Developer team ID.
APPLE_KEY_ID for Apple SIWA — Apple Sign-in key ID.
APPLE_AUTH_KEY_P8 for Apple token revocation — PEM contents of the Sign in with Apple .p8 private key; signs the client secret for token revocation on delete and unlink. Empty skips revocation.
EMAIL_APIKEY yes — API key for the transactional email provider (Resend).
ASSIST_BASE_URL optional from YAML OpenAI-compatible server root for the review model behind Backstage assist tasks. Empty leaves those tasks without a model.
ASSIST_MODEL optional from YAML Model name for the review model.
ASSIST_API_KEY optional — Bearer key for the review model's server.
ASSIST_DAILY_TOKEN_BUDGET optional 5000000 Review-model tokens per UTC day across all assist tasks. Spent, further calls stop until the next UTC day.
SEMANTIC_DAILY_TOKEN_BUDGET optional 2000000 Small-model tokens per UTC day, counted apart from the review model. Spent, further calls stop until the next UTC day.
CRASHES_API_TOKEN optional — Read-only API token for the crash-reporting project behind Backstage Crashes (org and project come from crashes: in the config yaml). Empty shows the view as not connected.
SUPPORT_INBOUND_SECRET optional — Shared secret that signs the inbound support email webhook. Empty turns /support/inbound off (404).
SMTP_HOST optional — SMTP fallback host (e.g. Mailtrap for local testing).
SMTP_USERNAME optional — SMTP username.
SMTP_PASSWORD optional — SMTP password.
WEBAUTHN_RP_ID yes (passkeys) from YAML WebAuthn Relying Party ID — domain only, e.g. localhost or tomoda.life.
WEBAUTHN_RP_ORIGIN yes (passkeys) from YAML Full origin including scheme, e.g. http://localhost:3000.
KLIPY_API_KEY for GIF picker — Klipy API key. Served to signed-in clients by GET /klipy/config; the app calls Klipy directly.
KLIPY_ADS_ENABLED no true (YAML klipy.ads_enabled) Tells clients (via GET /klipy/config) to request and show Klipy ads; on outside the EEA, UK and Switzerland.
SYNTHETIC_PROBE_EMAIL no synthetic+probe@tomoda.life Email of the synthetic-monitoring test user seeded at boot by migrate.SeedSyntheticAccounts (backend/internal/migrate/synthetic_accounts.go). The Cloudflare synthetic Worker logs in as this user to probe POST /api/v1/auth/login.
SYNTHETIC_PROBE_PASSWORD for login probe — Password for the synthetic test user. Empty = seed is skipped (suitable for local dev). In prod, sourced from GCP SM tomoda-synthetic-probe-password via ESO.
SYNTHETIC_PROBE_NAME no Synthetic Probe Display name for the synthetic user.
REVIEW_ACCOUNT_EMAIL no review@tomoda.life Sign-in email of the app-store review account seeded at boot by migrate.SeedSyntheticAccounts. See Synthetic accounts.
REVIEW_ACCOUNT_PASSWORD for review account none Password for the review account. Empty = seed is skipped. Sourced from GCP SM tomoda-review-account-password via ESO in dev and prod.
PHOTON_URL for self-host geocoder from YAML Base URL of the self-hosted Photon (OSM) geocoder. Falls back to disabled if blank.
PHOTON_ALLOW_PRIVATE for dev docker-network false When true, the outbound httpx.SafeClient may reach docker-network hosts (e.g. http://photon:2322). Off in prod (public Photon endpoint).
PHOTON_BIAS_SCALE no 0.2 Photon location_bias_scale for biased forward search: a light nudge toward the viewer, not a radius filter. Matches Photon's public default. A larger value buries distant/prominent results, so autocomplete feels nearby-only.
PHOTON_ZOOM no 14 Photon zoom hint for biased forward search, tuning the scale at which proximity matters.
FX_BASE_URL no https://api.frankfurter.dev (YAML) Exchange-rate API for approximate conversions (Currency → Conversion). Overrides fx.base_url; a self-hosted Frankfurter goes here. Disable by blanking fx.base_url in the YAML.
SERPER_API_KEY for link enrichment — Serper.dev key for the link-capture /search + /maps harvest. Empty disables enrichment (capture degrades to the deterministic parse).
ENABLE_SEARCH_ENRICHMENT for link enrichment false Kill-switch for Serper enrichment. Must be exactly true to enable; anything else disables.
ENABLE_BURST_SEED no false Turns on capture-picker harvesting: a cold area is filled from Serper /maps and minted as harvested rows. Must be exactly true. Needs SERPER_API_KEY and search enrichment enabled. See Capture-picker harvesting.
BURST_DAILY_CAP prod, with a Serper key 0 (no paid calls) Global safety ceiling on harvest Serper credits per day; at the ceiling, and at 0, the picker stays DB-only and enrichment skips paid calls. config.local.yaml sets 200. Production refuses to boot with a Serper key (or ENABLE_BURST_SEED) and no ceiling. The kill switch and a live override are in location_harvest_controls.
BURST_UNCAPPED no false Lets paid calls run with BURST_DAILY_CAP at 0. For test harnesses only; production refuses to boot with it.
BURST_PHOTO_DAILY_CEILING no 50000 Anomaly ceiling on harvested-place thumbnail downloads per day, not a throttle; 0 removes it. Past it the rehost stops, logs a warning and counts tomoda_locations_photo_rehost_total{outcome="ceiling"}.
CAPTURE_DAILY_PARSE_LIMIT no 50 Per-user/day budget for billable enrichment passes (Redis rate limit). Dev/admin accounts bypass.
ENRICH_DEFAULT_CITY no Ottawa Locale fallback for enrichment when a capture has no resolved place.
ENRICH_DEFAULT_GL no ca Serper country bias (gl) fallback, ISO 3166-1 alpha-2 lowercase.
SEMANTIC_ENABLED no from YAML Master switch for the semantic resolver. Off → enrichment uses the deterministic Serper heuristic only.
SEMANTIC_PROVIDER no openai_compat LLM transport; openai_compat (Ollama / llama.cpp / vLLM / OpenAI-style hosted) is the only value today.
SEMANTIC_BASE_URL for semantic layer from YAML Model server root (OpenAI-compatible chat API). Prod: https://api.deepseek.com. Local Ollama: http://semantic:11434.
SEMANTIC_MODEL for semantic layer from YAML Model id. Prod: deepseek-v4-flash. Local: qwen2.5:3b-instruct.
SEMANTIC_API_KEY for hosted provider — Bearer key. In prod, from GCP SM tomoda-deepseek-api-key via ESO. Empty for keyless self-host (Ollama).
SEMANTIC_TIMEOUT no 8s Per-call timeout (runs in the async enrich worker).
SEMANTIC_JSON_MODE no from YAML Request response_format: json_object from the server.
SEMANTIC_ALLOW_PRIVATE for dev docker-network false When true, the outbound httpx.SafeClient may reach docker-network hosts (e.g. http://semantic:11434). Off in prod.
EMBEDDINGS_ENABLED no false Master switch for semantic location and event search (Qwen3-Embedding-0.6B vectors). Off → search stays lexical-only.
EMBEDDINGS_BASE_URL for semantic search from YAML Text-embeddings (TEI) server root. Prod: the in-cluster TEI service; local: http://localhost:8085.
EMBEDDINGS_MODEL no from YAML Model id (Qwen/Qwen3-Embedding-0.6B); the TEI server hosts a single model, and the id selects the default query prefix.
EMBEDDINGS_DIMENSIONS no 1024 Stored vector length (the model output); must match the locations.embedding and events.embedding halfvec columns.
EMBEDDINGS_SEARCH_DIMENSIONS no 512 Leading slice of each vector that the HNSW index and queries use; query vectors are cut to it.
EMBEDDINGS_QUERY_PREFIX no model default Instruction prepended to query-side embeds only (\n is a newline). Defaults to the retrieval instruction for Qwen3-Embedding models and empty for others.
EMBEDDINGS_API_KEY for hosted provider — Bearer key; empty for keyless self-host (TEI).
EMBEDDINGS_TIMEOUT no 2s Per-call HTTP timeout. Search additionally caps its semantic step at 800 ms.
EMBEDDINGS_ALLOW_PRIVATE for dev/in-cluster false When true, the outbound httpx.SafeClient may reach private hosts (the TEI service).
ENRICH_BACKGROUND_PAID no true Gates the paid Serper/Places step in the background enrichment worker. task dev sets it false so seeding the catalog locally stays Serper-free (Photon gap-fill + embeddings still run). Interactive resolve/capture paths ignore it. Prod leaves it unset (true).
RANK_WEIGHT_NAME no 0.55 Name-match share of the composite search-ranking score. Unset keeps the shipped value; set to roll a retuned weight without a recompile.
RANK_WEIGHT_PROXIMITY no 0.12 Proximity (distance-decay) share of the search-ranking score.
RANK_WEIGHT_POPULARITY no 0.04 Popularity (saves + external rating) share of the search-ranking score.
RANK_WEIGHT_PROMINENCE no 0.08 Gazetteer-prominence share of the search-ranking score.
RANK_WEIGHT_SOURCE no 0.10 Source-trust (own catalog vs Photon) share of the search-ranking score.
RANK_WEIGHT_SEMANTIC no 0.11 Vector-similarity share of the search-ranking score.
RANK_WEIGHTS_REFRESH_INTERVAL no 2m How often the API ranker re-reads the active ranking_weights row and hot-swaps it in, so an approved retune applies without a redeploy. A Go duration (e.g. 90s, 5m). 0 disables the periodic refresh (boot-resolved weights stay).
FRONTEND_URL yes — Used to build email verification + password-reset links.
GIN_MODE no release Set to debug for verbose Gin logging.
SERVER_MODE no full Selects what the single backend binary starts. Values: full (everything, default for local), multi-hub (API + WS Hub, prod api deployment), async (Asynq worker + scheduler, prod async deployment), api-hub / ws-hub (reserved for the future api/ws split). Overridable per-pod via --mode flag. See Architecture → Decisions.

Pulling secrets locally

For day-to-day local dev you don't need to copy values into .env.local by hand. Run eval $(./scripts/dev/pull-secrets.sh) to pull from GCP Secret Manager into your shell, then task dev. See scripts.md for the full flow.

Frontend

Expo reads EXPO_PUBLIC_* variables at build time and bakes them into the JS bundle. In development they come from frontend/.env. For release builds, the wrapper script at frontend/scripts/release/build-with-secrets.sh pulls Sentry values from GCP Secret Manager and execs the build command (see scripts.md). The signing + upload secrets for a store build (match passphrase, App Store Connect API key, Android upload keystore, Play service account) are also pulled from GCP Secret Manager by the same script and exported only for the build process; see Signing for the inventory.

Variable Required? Default Purpose
EXPO_PUBLIC_API_URL yes — Base URL for the REST API, e.g. http://localhost:8080/api/v1 locally, https://api.tomoda.life/api/v1 in production.
EXPO_PUBLIC_WS_URL yes — Base URL for the WebSocket endpoint, e.g. wss://api.tomoda.life/ws.
EXPO_PUBLIC_WEB_URL no https://tomoda.life Marketing/web URL used for share links.
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID yes (Google login) hardcoded fallback Google OAuth web client ID.
EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID yes (iOS) hardcoded fallback Google OAuth iOS client ID.
EXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID yes (Android) hardcoded fallback Google OAuth Android client ID.
EXPO_PUBLIC_APP_VERSION no dev App version displayed in the admin dashboard footer. Also sent to Sentry as the release tag.
EXPO_PUBLIC_COMMIT_SHA no local Build commit SHA displayed in the admin dashboard footer.
EXPO_PUBLIC_BUILD_NUMBER no — Release build number. Sent to Sentry as the dist tag to disambiguate releases with the same version.
EXPO_PUBLIC_ENV no dev Environment label sent to Sentry (dev / prod). build-with-secrets.sh sets this to prod.
EXPO_PUBLIC_SENTRY_DSN no — Sentry project DSN. When empty, Sentry is fully disabled (no init, no captures). Pulled from GCP Secret Manager (tomoda-sentry-dsn) by frontend/scripts/release/build-with-secrets.sh at release-build time. Required for crash reporting in staging/prod builds — see Frontend → Observability.
EXPO_PUBLIC_SENTRY_ENV no falls back to EXPO_PUBLIC_ENV Optional override if you want a different Sentry environment label from the broader EXPO_PUBLIC_ENV.
SENTRY_AUTH_TOKEN for source-map upload — Build-time only, NEVER a public bundle. Auth token used by the Sentry CLI to upload source maps. Pulled from GCP Secret Manager (tomoda-sentry-auth-token) by build-with-secrets.sh. Not prefixed with EXPO_PUBLIC_ precisely because it must not ship to clients.
SENTRY_ORG for source-map upload tomoda Sentry organization slug used by the upload step. Defaults baked into app.config.js — override via env var if your org slug differs.
SENTRY_PROJECT for source-map upload tomoda-frontend Sentry project slug used by the upload step. Defaults baked into app.config.js — override via env var if your project slug differs.

EXPO_PUBLIC_* is public

Anything prefixed with EXPO_PUBLIC_ is baked into the client bundle and shipped to every user. Treat them as public. Never put secrets, server-only API keys, signing keys, database credentials, or anything you wouldn't paste into a tweet behind an EXPO_PUBLIC_ prefix. If you need a value at runtime that must stay secret, fetch it from the backend over an authenticated channel.

Where values come from in prod

Local: .env.local, defaults from pull-secrets.sh. Deployed: External Secrets syncs the tomoda-* GCP Secret Manager names into the pod env — see scripts/dev/pull-secrets.sh for the canonical mapping. Native release builds: frontend/scripts/release/build-with-secrets.sh pulls Sentry values from GCP Secret Manager and execs expo run:*. EXPO_PUBLIC_API_URL / EXPO_PUBLIC_WS_URL are hardcoded in frontend/app.config.js's production block.

If you add a new env var: register it in backend/config/config.go::Load, add it to env.example.local, document it here, and (if it's a secret used in dev/prod) add the GCP Secret Manager mapping to scripts/dev/pull-secrets.sh plus the K8s backend-secrets Secret in the devops/ repo.