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.