Configuration reference

Every variable below is read by the API from apps/api/.env, or from the environment of the API container. Everything except DATABASE_URL and AUTH_SECRET has a working default. Write a comment on its own line in these files. Compose reads KEY= # note as the value # note, because it treats # as a comment only when a space precedes it inside the value, so an empty variable with a trailing comment reaches the container holding that comment.

Three settings stop a deployment cold. AUTH_SECRET must be at least 32 characters or the API refuses to boot, and changing it signs out every user. Compose refuses to start when POSTGRES_PASSWORD or AUTH_SECRET is missing or empty from the root .env.

Required

Variable	Default	Required	Effect
`DATABASE_URL`	`postgresql://asobeast:asobeast@localhost:5433/asobeast`	Yes	PostgreSQL connection string. Compose sets it from `POSTGRES_PASSWORD`
`AUTH_SECRET`	None	Yes	Signs session cookies. At least 32 characters. Generate with `openssl rand -hex 32`

Core

Variable	Default	Required	Effect
`REDIS_HOST`	`localhost`	No	Host holding the BullMQ queues
`REDIS_PORT`	`6380`	No	Redis port
`REDIS_DB`	`0`	No	Redis database index for the queues. The end to end suite uses a separate index
`PORT`	`4000`	No	Port the API listens on
`DEFAULT_COUNTRY`	`us`	No	Home storefront used when an import URL carries no country segment
`LOG_LEVEL`	`debug`, and `log` in the Compose stack	No	One of `error`, `warn`, `log`, `debug`, `verbose`. Logs are JSON in production and human readable in development, and every line inside a request or job carries its workspace and correlation id. Compose lowers it to `log` because `debug` records every request, and container logs rotate at 10 MB across 3 files
`ACCOUNT_DELETION_GRACE_DAYS`	`7`	No	Days a scheduled workspace deletion stays reversible. The retention job erases the workspace on the first run after the grace period ends
`ERROR_TRACKING_DSN`	Empty	No	Sentry dsn for scrubbed error reports. Ignored unless `NODE_ENV` is `production` and `BILLING_ENABLED` is `true`, so a self hosted deployment never reports its errors to anyone else. Reports carry the error type, a secret scrubbed message and stack, the workspace and correlation id, and the request method with identifiers masked out of the path. They never carry headers, cookies, query strings, request bodies or account details. See Hosted observability

Scheduling

Every cron expression is evaluated in UTC. A CRON_ value anywhere on this page that is not a cron expression refuses to boot, rather than leaving that schedule and every one registered after it silently unscheduled. The one exception is an empty CRON_STORE_CANARY or CRON_STORE_STATUS, which removes that schedule. See The daily pipeline and rate limits.

Variable	Default	Required	Effect
`CRON_DAILY`	`0 3 * * *`	No	Starts the daily pipeline. Batched alerts flush after its processing completes, not on a clock
`CRON_SCORING`	`0 4 * * 0`	No	Recomputes popularity and difficulty weekly on Sunday
`CRON_RETENTION`	`0 5 * * *`	No	Prunes rows past their retention window
`CRON_AUDIT`	`0 6 * * *`	No	Writes the daily audit score snapshot
`CRON_LOCALIZATION_SWEEP`	`0 7 * * 1`	No	Probes the store once a week for the localizations every App Store app ships, so a localization added later is found and a removed one comes back only if the store still serves it. An empty value removes the schedule. See Which localizations does an app ship?
`CRON_DIGEST`	`0 8 * * 1`	No	Sends the weekly digest webhook on Monday
`CRON_PROXY_SYNC`	`0 2 * * *`	No	Reconciles the egress proxy pool against the provider. Never scheduled while `PROXY_PROVIDER` is `none`
`CRON_STORE_CANARY`	`0 2,8,14,20 * * *`	No	Asks each store whether it still parses, one hour before the daily run so the day’s first collection meets a known state. An empty value removes the schedule and switches the canary off. See Recover from a broken store parser

Collection rate limits

Variable	Default	Required	Effect
`SCRAPE_ITUNES_RPM`	`15`	No	iTunes requests per minute. The App Store worker runs concurrency 1 behind this limiter
`SCRAPE_GPLAY_RPM`	`10`	No	Google Play job starts per minute, not requests, because one job fans out to many

Raising either value risks the host IP address being throttled by the store. See The daily pipeline and rate limits.

Egress proxy pool

Optional. With PROXY_PROVIDER left at none every store request leaves from the host address, which is what a self hosted instance wants. Point it at a provider only when one address cannot carry the collection volume.

Variable	Default	Required	Effect
`PROXY_PROVIDER`	`none`	No	`none` disables the pool. `webshare` reconciles the pool against that account’s proxy list
`PROXY_API_URL`	`https://proxy.webshare.io/api/v2`	No	Provider API base URL
`PROXY_API_KEY`	Empty	When a provider is set	Provider API key. The API refuses to boot when a provider is configured without one
`PROXY_USERNAME`	Empty	No	Credentials shared across the pool. Leave empty for an IP authorized account
`PROXY_PASSWORD`	Empty	No	Password for `PROXY_USERNAME`
`PROXY_ENDPOINT_RPM`	`15`	No	Requests per minute allowed per pool endpoint. This is the limiter that replaces the single host budget once the pool is on
`PROXY_ACQUIRE_TIMEOUT_MS`	`120000`	No	How long a job waits for a free endpoint each time it asks. A saturated pool delays work rather than dropping it: once this budget runs out the job goes back to the queue, delayed by a few seconds, without spending one of its attempts, and only a job still waiting a day after it was queued fails. A shutdown ends the wait at once, so the budget never holds up a drain
`PROXY_WORKER_MAX_CONCURRENCY`	`8`	No	Ceiling for store worker concurrency once the pool is on. Actual concurrency tracks the healthy endpoint count and falls back as endpoints cool down. Ignored while `PROXY_PROVIDER` is `none`

A job holds its endpoint for its whole run, so two requests to the same store never leave through one address at once, unless a job outlives the five minute hold. When the job ends, the endpoint stays paced until the requests it made fit PROXY_ENDPOINT_RPM, counted from the moment the job took it, and never less than one request interval after the last request it sent. A job that failed is paced the same way. Google Play orders its search results by the country of the address a request comes from, so a queued Google Play job for a storefront waits for a healthy pool endpoint in that country instead of leaving through one abroad, and borrows another country’s endpoint only while every endpoint in its own country is cooling down. A name search and the keyword and competitor suggestion lookups, which someone is waiting for and whose answers are never stored, still prefer their own country but take a free endpoint abroad rather than wait for a busy one. The App Store answers the same from any address and takes whichever endpoint is free first. Google Play collection for a storefront is therefore bounded by the endpoints in that country: place them where your Google Play keywords are, because a job that finds its country’s endpoints busy for longer than PROXY_ACQUIRE_TIMEOUT_MS goes back to the queue and waits its turn again. With PROXY_PROVIDER at none the store workers keep concurrency 1 behind SCRAPE_ITUNES_RPM and SCRAPE_GPLAY_RPM. Those two variables never change meaning: they describe the budget of a single egress address, which is exactly what a self hosted instance has. Credentials stay in configuration. The database records only which credential a pool endpoint uses, never the secret itself.

Residential fallback

Datacenter addresses carry the traffic. A residential gateway is an emergency path for a single request that a datacenter address was blocked on, never a primary route, because residential bandwidth is metered and costs orders of magnitude more per request.

Variable	Default	Required	Effect
`PROXY_RESIDENTIAL_URL`	Empty	No	Gateway used only after a datacenter address is blocked. Empty disables the fallback
`PROXY_RESIDENTIAL_USERNAME`	Empty	No	Gateway credentials
`PROXY_RESIDENTIAL_PASSWORD`	Empty	No	Password for `PROXY_RESIDENTIAL_USERNAME`
`PROXY_RESIDENTIAL_MONTHLY_CAP_USD`	`0`	No	Hard monthly ceiling. Every residential request is claimed against it before it leaves, so a job that fans out to many requests stops at the ceiling rather than crossing it. At `0` every fallback is refused, so a broad block cannot turn into an unbounded bill
`PROXY_RESIDENTIAL_COST_PER_GB`	`3`	No	Provider list price, used to price the cap
`PROXY_RESIDENTIAL_MB_PER_REQUEST`	`1.2`	No	Measured average response size. With the price per gigabyte this estimates month to date spend
`SIGNUP_CAPACITY_MAX_UTILIZATION`	`0`	No	`0` disables the gate. Above `0`, registration is refused with `503` once tracked collection passes this share of daily capacity. Applied only when `BILLING_ENABLED` is `true`, so a self hosted instance is never gated

Alerts

See Send alerts.

Variable	Default	Required	Effect
`ALERT_DELIVERY`	`batched`	No	`batched` sends up to two scoped reports per channel after daily processing completes. `instant` sends one notification per event. Warns in production when `instant` has no SMTP configured. Webhook subscriptions live in the database, so configuration validation cannot see them
`ALERT_RANK_DROP_THRESHOLD`	`5`	No	Positions a primary app must move before `rank.dropped` or `rank.improved` fires
`ALERT_REVIEW_SCORE_MAX`	`2`	No	Highest star rating treated as a negative review. Accepts 1 to 4
`ALERT_ACTIONS_MIN_PRIORITY`	`high`	No	Lowest priority that fires `action.opened`. One of `critical`, `high`, `medium`, `low`
`WEBHOOK_ALLOW_PRIVATE_TARGETS`	`false`	No	`false` keeps alert webhooks on public addresses. Loopback, private, carrier grade NAT, link local and cloud metadata targets are refused when the webhook is registered and again when the connection is made, so a hostname that resolves to an internal address cannot reach it either. `true` opts a self hosted instance in to delivery on its own network, including a receiver named by a bare hostname such as a Compose service, or by `localhost`. Refuses to boot when `true` with `BILLING_ENABLED` set to `true`, because the url belongs to the customer, and warns in production otherwise
`WEB_PUBLIC_URL`	Empty	No	Public web origin, `http` or `https` only, and any other scheme refuses to boot. Builds every link in an email (confirmation, password reset, invitation, the button back into the app, the logo and the unsubscribe link), deep links inside alert payloads and the Stripe return address, and is the single origin CORS allows. One click unsubscribe headers are added only when it is `https`. Unset leaves an alert link `null`, sends emails without buttons, logo or unsubscribe links, closes checkout, sends no CORS headers, refuses account recovery with `503` because its link would carry no host, and refuses to boot when `BILLING_ENABLED` is `true` with SMTP configured, because confirmation is mandatory there. A new email alert recipient always waits for confirmation, and without this no confirmation email can be sent, so the recipient never receives an alert. Warns in production when SMTP is configured and this is empty, or names this machine (`localhost`, `127.0.0.1` or `[::1]`), because no recipient elsewhere can open its links. The Compose stacks set it themselves, see Compose only

Email delivery

Email stays disabled until both SMTP_HOST and SMTP_FROM are set. Email is optional on a self hosted instance and mandatory on a metered one. With BILLING_ENABLED=true in production and no mail path, the API warns at boot that it can confirm no address, warn nobody before a trial ends, and recover no forgotten password. See Hosting behind TLS and a reverse proxy.

Variable	Default	Required	Effect
`SMTP_HOST`	Empty	No	SMTP server host. Required to enable email
`SMTP_PORT`	`587`	No	Use `465` with `SMTP_SECURE=true`, otherwise 587 or 25
`SMTP_SECURE`	`false`	No	`true` wraps the connection in TLS from the start, which port 465 expects. Warns in production when `true` on any other port
`SMTP_USER`	Empty	No	Leave empty for an unauthenticated relay
`SMTP_PASSWORD`	Empty	No	Paired with `SMTP_USER`
`SMTP_FROM`	Empty	No	From address such as `asobeast <[email protected]>`. Required to enable email
`SMTP_DKIM_DOMAIN`	Empty	No	Signs every email with DKIM for this domain, which should be the `SMTP_FROM` domain or its parent so DMARC aligns. The three `SMTP_DKIM_` variables are set together or not at all, and the API refuses to boot when only some are set
`SMTP_DKIM_SELECTOR`	Empty	No	DKIM selector. Publish the public key at `<selector>._domainkey.<domain>`
`SMTP_DKIM_PRIVATE_KEY_PATH`	Empty	No	RSA private key in PEM, for example `keys/dkim-private.pem`. A relative path resolves against `apps/api`, which both Compose stacks mount read only at `apps/api/keys`. The API refuses to boot when the three are set and the file cannot be read. Its contents are never logged

Action Center

See Work the Action Center.

Variable	Default	Required	Effect
`ACTIONS_MAX_OPEN_PER_APP`	`20`	No	New actions one generation run may open per app, highest impact first. Existing open and snoozed actions always refresh
`ACTIONS_SNOOZE_MAX_DAYS`	`90`	No	Furthest a snooze may be set into the future

Screenshot captions

See Read screenshot captions.

Variable	Default	Required	Effect
`SCREENSHOT_OCR`	`true`	No	Reads the large caption text printed on App Store screenshots on this machine. `false` still records the screenshot list and detects replaced or reordered screenshots, but downloads and reads no screenshots. A changed icon address still downloads its two renditions to compare the pixels, so a store-side address rotation is not recorded as a change
`SCREENSHOT_OCR_LANGUAGES`	`eng,deu,fra,spa,por,ita,jpn,kor,chi_sim,chi_tra,rus,ara,tha,pol`	No	The bundled language packs the reader may use. A storefront reads English plus its own language when that pack is listed. The API refuses to boot on a name that is not bundled

Data retention

0 means keep forever. Pruning runs on CRON_RETENTION.

Variable	Default	Required	Effect
`RETENTION_RANKINGS_DAYS`	`365`	No	Prunes keyword positions older than N days
`RETENTION_SERP_DAYS`	`90`	No	Prunes SERP entries older than N days
`RETENTION_SERP_DEEP_DAYS`	`30`	No	Prunes SERP entries below the top 10 older than N days; `0` keeps them as long as `RETENTION_SERP_DAYS`
`RETENTION_SNAPSHOTS_DAYS`	`180`	No	Prunes app snapshots older than N days. The newest snapshot per app and market is always kept
`RETENTION_CATEGORY_RANKS_DAYS`	`365`	No	Prunes category ranks older than N days
`RETENTION_CHARTS_DAYS`	`365`	No	Prunes top chart captures older than N days. `0` keeps forever
`RETENTION_CHANGE_EVENTS_DAYS`	`0`	No	Prunes metadata change events older than N days
`RETENTION_DELIVERIES_DAYS`	`30`	No	Prunes alert delivery log rows older than N days
`RETENTION_ALERT_EVENTS_DAYS`	`30`	No	Prunes completed alert claims older than N days. Unfinished claims are always retained
`RETENTION_AUDIT_SCORES_DAYS`	`0`	No	Prunes audit score history older than N days
`RETENTION_ACTIONS_DAYS`	`180`	No	Prunes closed action items only. Open and snoozed actions are never pruned by age
`RETENTION_AI_CALLS_DAYS`	`400`	No	Days the AI call ledger is kept. Never prunes the current month, which the monthly AI allowance still counts. `0` keeps forever
`RETENTION_STORE_REPORTS_DAYS`	`35`	No	Days a downloaded store console report file is kept so it can be read again after a parser change. The funnel rows built from it are never pruned by age. `0` keeps forever, which is not recommended because the files grow with every app and day
`RETENTION_BILLING_EVENTS_DAYS`	`90`	No	Days to keep stored Stripe webhook payloads, which carry customer billing details. `0` keeps them forever

Runtime

Variable	Default	Required	Effect
`NODE_ENV`	`development`	No	`development`, `test` or `production`. The Docker image sets `production`, which turns on the configuration guards below

Two combinations are individually valid and jointly unsafe, so the API refuses to start on them rather than logging a warning nobody reads. Five more warn at startup. See Hosting and network exposure.

Authentication

See Authentication and accounts.

Variable	Default	Required	Effect
`AUTH_SESSION_DAYS`	`7`	No	Session cookie lifetime in days
`AUTH_ALLOW_REGISTRATION`	`false`	No	`true` keeps signups open. `false` closes registration once the first account exists. The first account always bootstraps as owner
`AUTH_REGISTRATION_WORKSPACE`	`own`	No	Where a self registration lands. `own` gives every sign up a workspace of its own, so someone who registers never sees the apps, keywords and rankings already tracked on the instance. `shared` puts every sign up in the bootstrap workspace as a member, which suits an instance whose sign ups are all trusted with that data. Refuses to boot when `shared` and `BILLING_ENABLED` is `true`. Warns in production when `shared` and `AUTH_ALLOW_REGISTRATION` is `true`. See Authentication and accounts
`STRIPE_SECRET_KEY`	empty	No	Enables billing. Absent, every Stripe path is inert and the API boots normally. Never logged. Give every environment its own sandbox, because a sandbox shared with another stack posts that stack’s events here. Warns in production when `BILLING_ENABLED=true` on a sandbox key (`sk_test_` or `rk_test_`)
`STRIPE_WEBHOOK_SECRET`	empty	No	Verifies the webhook endpoint. Absent, the endpoint refuses every delivery, because an unverified endpoint hands out subscriptions, and checkout stays closed so nobody pays for access that could never be provisioned
`STRIPE_PORTAL_RETURN_URL`	empty	No	Where the customer portal returns to. Falls back to `WEB_PUBLIC_URL` plus `/settings`
`STRIPE_TAX_ENABLED`	`false`	No	Adds automatic tax to every checkout session. Needs Stripe Tax active with its registrations and prices that carry a tax behaviour, or Checkout refuses to open. Address and tax id are collected either way. Refuses to boot together with `STRIPE_MANAGED_PAYMENTS=true`. See Billing
`STRIPE_MANAGED_PAYMENTS`	`false`	No	Sells every checkout through Stripe Managed Payments, so Stripe is the merchant of record and calculates, collects and remits the tax. Needs Managed Payments activated in the Stripe dashboard. Refuses to boot together with `STRIPE_TAX_ENABLED=true`. Warns in production when `BILLING_ENABLED=true` runs on a live key with neither this nor `STRIPE_TAX_ENABLED`. See Billing
`STRIPE_PRICE_INDIE_MONTHLY`	empty	No	Price id for Indie monthly. Empty resolves it from the lookup key `asobeast_indie_month`, which `pnpm --filter api stripe:catalog` creates, at boot and before every reconciliation. Setting any of the four `STRIPE_PRICE_*` replaces the lookup key catalog with the ids they name, so set all four or none
`STRIPE_PRICE_INDIE_YEARLY`	empty	No	Price id for Indie annual. Empty resolves it from `asobeast_indie_year`
`STRIPE_PRICE_ULTIMATE_MONTHLY`	empty	No	Price id for Ultimate monthly. Empty resolves it from `asobeast_ultimate_month`
`STRIPE_PRICE_ULTIMATE_YEARLY`	empty	No	Price id for Ultimate annual. Empty resolves it from `asobeast_ultimate_year`
`CRON_BILLING_RECONCILE`	`0 7 * * *`	No	Daily reconciliation of local subscription state against Stripe, UTC
`CRON_TRIAL_NOTICES`	`0 9 * * *`	No	Daily sweep that sends the trial milestone emails, UTC
`AUTH_COOKIE_SECURE`	`false`	No	Marks the session cookie `Secure`. Refuses to boot when `false` and `NODE_ENV` is `production`. The Docker image sets `NODE_ENV=production`, so the Compose stack defaults this to `true`
`TRUST_PROXY`	`0`, and `1` pinned in the Compose stack	No	How many proxies you control sit between the internet and the API, counting the web app as one. Compose pins it to `1` because the web app is always exactly one hop in front of the API there. `true` means 1 and `false` means 0. The API reads that many entries back from the right of `X-Forwarded-For`, so auth throttling keys on the real client address. Both apps warn at startup in production when `0`. See Hosting

Entitlements

Variable	Default	Required	Effect
`BILLING_ENABLED`	`false`	No	`true` starts every new account on a trial and answers `402` once it lapses, until the plan is `indie` or `ultimate`
`TRIAL_DAYS`	`7`	No	Trial length in days when `BILLING_ENABLED=true`. Refuses to boot at `0` with billing enabled, because every new account would be locked out immediately

Published store status

An opt-in outbound integration, off by default. When STORE_STATUS_URL is empty no request is ever made and the poll is not even scheduled. See What leaves your deployment and Recover from a broken store parser.

Variable	Default	Required	Effect
`STORE_STATUS_URL`	Empty	No	Url of a published store status document. Setting it opts this deployment in to an hourly bare `GET` of that url, so a store breakage the maintainer already knows about can be announced without waiting for the local canary. Empty means no request is ever made. Give the final url: a redirect is not followed
`CRON_STORE_STATUS`	`17 * * * *`	No	When the poll runs, UTC. The odd minute is deliberate, so installations do not all arrive at the top of the hour. Never scheduled while `STORE_STATUS_URL` is empty. An empty value removes the schedule

The poll goes through the same public only address guard that alert webhooks use, so a url resolving to a loopback, private, link local or cloud metadata address is refused at both configuration and connection time. A failed or stale poll never changes what the local canary reported.

Optional AI

See Enable the optional AI features.

Variable	Default	Required	Effect
`OPENAI_API_KEY`	Empty	No	Empty disables every AI feature. With `OPENAI_BASE_URL` set, the key of that provider; any non empty value for a local server that checks none
`OPENAI_BASE_URL`	Empty	No	Address of an OpenAI compatible API the AI features call instead of OpenAI, for example `https://openrouter.ai/api/v1`. Empty uses `https://api.openai.com/v1`. Refuses to boot when it is not an http or https URL, carries a user name or password, or holds a `#` fragment. See Use an OpenAI compatible provider
`AI_MODEL`	`gpt-5.6-luna`	No	The model name as the provider spells it. Must support vision and structured outputs, because the audit reads screenshots
`AI_CALLS_PER_MONTH`	Empty	No	AI calls each workspace may make per calendar month (UTC) on a self hosted instance. Empty means unlimited and `0` turns AI calls off. Ignored when `BILLING_ENABLED` is true, where each plan sets its own allowance. Warns in production when empty while `OPENAI_API_KEY` is set and registration is open

Apple search popularity

Optional, off by default. With an Apple Ads API key, asobeast reads Apple’s own weekly search popularity for the App Store terms it covers instead of estimating them. See Keyword scoring.

Variable	Default	Required	Effect
`APPLE_ADS_CLIENT_ID`	Empty	No	Client id from the API page of your Apple Ads account settings. The four credentials are set together or not at all, and a partial set refuses to boot
`APPLE_ADS_TEAM_ID`	Empty	No	Team id from the same page
`APPLE_ADS_KEY_ID`	Empty	No	Key id Apple returned when you uploaded the public key
`APPLE_ADS_PRIVATE_KEY_PATH`	Empty	No	Path to the `prime256v1` private key PEM. A relative path resolves against `apps/api`, and both Compose stacks mount `apps/api/keys` there read only, so `keys/apple-ads-private.pem` works with and without Docker. When the four credentials are set and the path is not a readable file, the API refuses to boot. Its contents are never logged
`APPLE_ADS_AD_ACCOUNT_ID`	Empty	No	Ad account to read through. Empty uses the first one the credentials can read
`CRON_APPLE_POPULARITY`	`0 9 * * 1`	No	When the weekly sync runs, UTC. Never scheduled while the credentials are unset

Store consoles

Optional, off by default. Owners connect their store consoles in Integrations; these keys protect what they paste. See Read impressions and conversion from your console.

Variable	Default	Required	Effect
`STORE_CONNECT_ENCRYPTION_KEY`	Empty	No	Base64 of 32 random bytes, generated with `openssl rand -base64 32`. Seals the App Store Connect and Play Console keys owners connect in Integrations. Empty keeps every store connection off, and nothing contacts Apple or Google. A value that is not 32 bytes refuses to boot. Never logged
`STORE_CONNECT_ENCRYPTION_KEY_PREVIOUS`	Empty	No	The key being rotated away from. A stored credential sealed with it is opened and resealed with the current key on first use. Refuses to boot when set without `STORE_CONNECT_ENCRYPTION_KEY`
`GOOGLE_PLAY_OAUTH_CLIENT_ID`	Empty	No	Client ID of a Google Cloud OAuth client of type Web application whose authorized redirect URI is `WEB_PUBLIC_URL` followed by `/integrations/google-play`. With the secret and `WEB_PUBLIC_URL` it lets owners connect Google Play by signing in with Google instead of a service account key. Set both `GOOGLE_PLAY_OAUTH_` variables or neither; one alone refuses to boot
`GOOGLE_PLAY_OAUTH_CLIENT_SECRET`	Empty	No	Client secret of that OAuth client. Publish its consent screen to production, or Google expires every sign in after seven days. Never logged
`CRON_STORE_REPORTS`	`30 5 * * *`	No	When the daily download of the reports each connected console published runs, UTC. Never scheduled while `STORE_CONNECT_ENCRYPTION_KEY` is empty

Admin surfaces

See The queue dashboard and the OpenAPI surface.

Variable	Default	Required	Effect
`BULL_BOARD_ENABLED`	`true`	No	Serves the queue dashboard at `/admin/queues`. `false` removes it entirely
`API_DOCS`	`owner`	No	Who may read `/docs`, `/docs-json` and `/docs-yaml`. `owner`, `public` or `off`. Warns in production when `public`
`METRICS_CACHE_SECONDS`	`30`	No	How long one `/metrics` scrape is reused before the collectors run again. `0` collects on every scrape
`BACKUP_MAX_AGE_HOURS`	`0`	No	Hours a backup may go without reporting a completed run before `backup.stale` fires. `0` expects no backup and never alerts. See Backups
`DISK_BUDGET_BYTES`	`0`	No	Bytes the database may occupy before `storage.headroom.low` fires, which is what the partition can spare rather than what it holds. `0` declares no budget and never alerts. See Capacity and limits

Compose only

These live in the root .env and are read by Compose, not by the API directly.

Variable	Default	Required	Effect
`POSTGRES_PASSWORD`	None	Yes	Sets the PostgreSQL role password and is interpolated into `DATABASE_URL`
`AUTH_SECRET`	None	Yes	Passed through to the API container
`WEB_PUBLIC_URL`	`http://localhost:3001`	No	Passed to the API container in place of any value in `apps/api/.env`, which `pnpm dev` reads on port 3000. Set it to the origin a person would type when a proxy or another host serves the stack. The tunnel overlay replaces it with `https://` and `ASOBEAST_DOMAIN`
`TRUST_PROXY`	`0`	No	Hops you control in front of the web app. The tunnel overlay pins `1` for the web app whatever this file says, because the tunnel is always exactly one hop. Set it yourself when you run `cloudflared` on the host or bring your own proxy
`TUNNEL_TOKEN`	None	With the tunnel overlay	Token of the Cloudflare Tunnel you created in the dashboard. Read only by `docker-compose.tunnel.yml`
`ASOBEAST_DOMAIN`	None	With the tunnel overlay	Public hostname attached to that tunnel. Becomes `WEB_PUBLIC_URL`

See Hosting behind TLS and a reverse proxy for the overlay and for how to verify the hop count against the real chain.

Retired variables

BULL_BOARD_USER and BULL_BOARD_PASSWORD are ignored. The queue dashboard now requires a session or a personal API token of the platform operator instead of basic authentication, and the API logs a warning at boot if either variable is still set. Remove them.

Keeping this page correct

This page and the .env.example files change in the same commit. If a default here disagrees with apps/api/.env.example, the file is right and this page is a bug.

Get started

Install

Concepts

Guides

Configuration

Operations

Hosted operations

Legal

Reference

Configuration reference

Required

Core

Scheduling

Collection rate limits

Egress proxy pool

Residential fallback

Alerts

Email delivery

Action Center

Screenshot captions

Data retention

Runtime

Authentication

Entitlements

Published store status

Optional AI

Apple search popularity

Store consoles

Admin surfaces

Compose only

Retired variables

Keeping this page correct

​Required

​Core

​Scheduling

​Collection rate limits

​Egress proxy pool

​Residential fallback

​Alerts

​Email delivery

​Action Center

​Screenshot captions

​Data retention

​Runtime

​Authentication

​Entitlements

​Published store status

​Optional AI

​Apple search popularity

​Store consoles

​Admin surfaces

​Compose only

​Retired variables

​Keeping this page correct

Required

Core

Scheduling

Collection rate limits

Egress proxy pool

Residential fallback

Alerts

Email delivery

Action Center

Screenshot captions

Data retention

Runtime

Authentication

Entitlements

Published store status

Optional AI

Apple search popularity

Store consoles

Admin surfaces

Compose only

Retired variables

Keeping this page correct