Self-Hosting Guide & Environment Reference

This guide is for platform engineers and developers running a custom, self-hosted instance of toorow.

Self-hosted instances operate in complete isolation. By default, toorow sends no telemetry, phone-home data, or analytics to the maintainers. See Security Constraints for details.

1. Account & Infrastructure Setup

To deploy a functional self-hosted instance, provision the following services:

Platform Database (PostgreSQL 15+): Create a PostgreSQL instance (e.g., Supabase project or Cloud SQL). Apply platform migrations located in infra/nango/migrations/ (migrations 001 to 029).
Google Cloud Project (Analytics Warehouse & Google OAuth):
- Enable BigQuery, Cloud Run, and Google APIs (Analytics Data, Search Console, Google Ads, Sheets).
- Provision BigQuery datasets (raw_*, marts_*) and a Service Account with roles/bigquery.dataEditor and roles/bigquery.jobUser. Use the Terraform scripts in infra/terraform/ (terraform plan/apply).
- Create a Web OAuth 2.0 Client ID for Google connectors.
Nango Broker (Non-Google OAuth):
- Deploy Nango OSS using infra/nango/docker-compose.yml or create a Nango Cloud account.
- Register provider apps (Meta Ads, TikTok, LinkedIn, Shopify, Stripe, Klaviyo) in Nango.

2. Environment Variable Reference (`.env`)

Copy .env.example to .env in your deployment environment and configure the required parameters.

Server & Network Security

Variable	Type	Default	Description
`PORT`	Integer	`8000`	HTTP listening port for the server. Injected automatically by Cloud Run (`8080`).
`HOST_HEADER_VALIDATION`	String	`strict`	Set to `strict` to enforce Host header validation against `ALLOWED_HOST`.
`ALLOWED_HOST`	String	`localhost:8000`	Allowed HTTP Host header value (e.g., `your-api.run.app`).
`FASTMCP_HTTP_HOST_ORIGIN_PROTECTION`	Boolean	`true`	Enables FastMCP native host/origin validation.
`FASTMCP_HTTP_ALLOWED_HOSTS`	String	Unset	Comma-separated list of allowed origins for FastMCP HTTP transport.

Authentication Mode (`TOOROW_AUTH_MODE`)

Variable	Type	Allowed Values	Description
`TOOROW_AUTH_MODE`	String	`disabled`, `static`, `oauth`	`disabled`: No auth (local tests only). `static`: Static token map for QA. `oauth`: RS256 JWT verification (mandatory for production).
`TOOROW_STATIC_TOKEN`	String	Unset	Static secret token required when `TOOROW_AUTH_MODE=static`.
`TOOROW_JWT_PUBLIC_KEY`	String	Unset	PEM RS256 public key (with literal `\n`) for verifying caller JWTs in OAuth mode.
`TOOROW_JWKS_URI`	String	Unset	Remote JWKS JSON endpoint URL (alternative to public key string).
`TOOROW_JWT_ISSUER`	String	Unset	Required JWT issuer claim (`iss`) matching incoming OAuth tokens.
`TOOROW_JWT_AUDIENCE`	String	Unset	Required JWT audience claim (`aud`) matching `connector-api`.

Platform Database & Key Governance

Variable	Type	Default	Description
`PLATFORM_DB_URL`	String	`postgresql://...`	Connection URI for the PostgreSQL platform database (connections, audit logs, queue).
`TENANT_KEY_BACKEND`	String	`local`	Encryption key backend for tenant metadata: `local` (Phase A file) or `secret_manager` (GCP Secret Manager).
`TENANT_KEY_DIR`	String	`infra/keys`	Local directory for tenant encryption keys when `TENANT_KEY_BACKEND=local`.

OAuth Brokers & Providers

Variable	Type	Purpose
`NANGO_BASE_URL`	String	Base URL of Nango instance (e.g., `https://api.nango.dev` or `http://localhost:3003`).
`NANGO_SECRET_KEY`	String	Secret API key generated in Nango console.
`GOOGLE_OAUTH_CLIENT_ID`	String	Google Web Application OAuth Client ID.
`GOOGLE_OAUTH_CLIENT_SECRET`	String	Google Web Application OAuth Client Secret.
`GOOGLE_OAUTH_REDIRECT_URI`	String	OAuth redirect URI (must match GCP console URI, e.g., `https://<host>/api/google/oauth/callback`).
`GOOGLE_OAUTH_STATE_SECRET`	String	Secret key for signing anti-CSRF OAuth state tokens (`python -c "import secrets; print(secrets.token_hex(32))"`).

Background Queue & Scheduler

Variable	Type	Default	Description
`QUEUE_BACKEND`	String	`local`	Job queue backend: `local` (Postgres worker thread) or `cloud_tasks` (GCP Cloud Tasks).
`QUEUE_POLL_INTERVAL_SECONDS`	Integer	`5`	Polling frequency for local queue worker.
`SCHEDULER_ENABLED`	Boolean	`false`	Enables in-process nightly scheduler thread. Set `true` in production containers.
`SCHEDULER_NIGHTLY_HOUR`	Integer	`2`	Fallback local hour (0–23) for a Datastream that carries no moment of its own. A Datastream with its own cadence ignores it.
`SCHEDULER_TIMEZONE`	String	`Europe/Paris`	IANA timezone string for computing daily boundaries (`yesterday`).
`CLOUD_TASKS_PROJECT`	String	—	GCP project owning the Cloud Tasks queue. Required when `QUEUE_BACKEND=cloud_tasks`.
`CLOUD_TASKS_LOCATION`	String	—	Queue region, e.g. `europe-west1`.
`CLOUD_TASKS_QUEUE_NAME`	String	—	Queue name the tasks are created in.
`CLOUD_TASKS_WORKER_URL`	String	—	Public base URL of this service. Tasks are pushed to `<url>/internal/worker/...`.
`INTERNAL_ENDPOINTS_REQUIRE_HEADER`	String	—	Shared secret for `X-Internal-Auth`. Mandatory under `cloud_tasks`: without it no task can authenticate and every scheduled call answers `503`. One value per deployment — not per user.
`QUEUE_RECONCILE_GRACE_SECONDS`	Integer	`300`	How long a committed job may sit unclaimed before the reconciliation sweep presumes its task was lost.
`PUBSUB_TOPIC`	String	—	Full topic path for published facts. Absent = facts are recorded and logged, never published. Not an error.

If your host suspends the container between requests, QUEUE_BACKEND=local will not run your scheduled work.The local backend relies on three in-process daemon threads (queue worker, nightly scheduler, health poller). On a platform that allocates CPU only during request handling — Google Cloud Run with --min-instances=0 is the reference case — those threads only advance while a request happens to be in flight, so nightly retrieval may never fire and nothing records that it did not.Choose one:

cloud_tasks with Cloud Scheduler driving /internal/scheduler/* (see Cloud Hosting);
or local on a host that keeps the process running continuously (a VM, a container with always-allocated CPU, docker-compose).

SCHEDULER_ENABLED=true alone does not make an idle-suspended container run its scheduler.

Read-Through Cache (DuckDB)

Variable	Type	Default	Description
`TOOROW_CACHE_ENABLED`	Boolean	`false`	Set `true` to enable ephemeral read-through cache for fast query responses (~50ms).
`TOOROW_CACHE_PATH`	String	`cache_warehouse.duckdb`	Distinct DuckDB file path for caching recent marts.
`TOOROW_CACHE_WINDOW_DAYS`	Integer	`30`	Rolling day window included in the ephemeral cache.
`TOOROW_CACHE_TABLES`	String	Default marts	Comma-separated list of analytical marts cached (`fact_daily_kpi,semantic_ctr,semantic_cpa,semantic_roas`).

Optional Telemetry & Tracing

Variable	Type	Default	Description
`TRACING_ENABLED`	Boolean	`false`	Set `true` to enable OpenTelemetry spans exported to Langfuse (`uv sync --extra tracing`).
`LANGFUSE_PUBLIC_KEY`	String	Unset	Langfuse project public key.
`LANGFUSE_SECRET_KEY`	String	Unset	Langfuse project secret key.
`LANGFUSE_HOST`	String	`http://localhost:3004`	Langfuse host URL.
`GA4_MP_MEASUREMENT_ID`	String	Unset	Optional server-side GA4 Measurement Protocol ID (`G-XXXXXXX`). Unset = zero telemetry.
`GA4_MP_API_SECRET`	String	Unset	Optional GA4 Measurement Protocol API secret. Unset = zero telemetry.

3. Container Deployment (Cloud Run)

Build Container Image:

docker build -t europe-west1-docker.pkg.dev/<PROJECT_ID>/connector/mcp-server:latest -f infra/docker/mcp-server/Dockerfile .

Push Image & Deploy:

docker push europe-west1-docker.pkg.dev/<PROJECT_ID>/connector/mcp-server:latest

gcloud run deploy mcp-server \
  --image europe-west1-docker.pkg.dev/<PROJECT_ID>/connector/mcp-server:latest \
  --region europe-west1 \
  --platform managed \
  --min-instances=0 \
  --max-instances=4 \
  --set-env-vars "TOOROW_AUTH_MODE=oauth,TOOROW_JWT_JWKS_URI=https://<your-auth-provider>/.well-known/jwks.json,HOST_HEADER_VALIDATION=strict,ALLOWED_HOST=<your-domain>"

Next Steps & Cross-References

Prerequisites

Verify required GCP APIs, service accounts, and database connections.

Security Constraints

Review the pre-live security checklist and architectural invariants.

Cloud Hosting

Examine the maintainers’ managed Cloud Run setup.

Developer Quickstart

Run a lightweight local sandbox instance for testing.

Self-Hosted Deployment

Self-Hosted Engineering & Connectors

Self-Hosting Guide & Environment Reference

1. Account & Infrastructure Setup

2. Environment Variable Reference (`.env`)

Server & Network Security

Authentication Mode (`TOOROW_AUTH_MODE`)

Platform Database & Key Governance

OAuth Brokers & Providers

Background Queue & Scheduler

Read-Through Cache (DuckDB)

Optional Telemetry & Tracing

3. Container Deployment (Cloud Run)

Next Steps & Cross-References

Prerequisites

Security Constraints

Cloud Hosting

Developer Quickstart

​1. Account & Infrastructure Setup

​2. Environment Variable Reference (.env)

​Server & Network Security

​Authentication Mode (TOOROW_AUTH_MODE)

​Platform Database & Key Governance

​OAuth Brokers & Providers

​Background Queue & Scheduler

​Read-Through Cache (DuckDB)

​Optional Telemetry & Tracing

​3. Container Deployment (Cloud Run)

​Next Steps & Cross-References

Prerequisites

Security Constraints

Cloud Hosting

Developer Quickstart

1. Account & Infrastructure Setup

2. Environment Variable Reference (`.env`)

Server & Network Security

Authentication Mode (`TOOROW_AUTH_MODE`)

Platform Database & Key Governance

OAuth Brokers & Providers

Background Queue & Scheduler

Read-Through Cache (DuckDB)

Optional Telemetry & Tracing

3. Container Deployment (Cloud Run)

Next Steps & Cross-References