Environment variables
.env.example lists exactly the variables the site reads, each with a comment. Copy it to .env for development; on a server, set the same names in the container's or platform's settings.
- Required:
DATABASE_URLandPAYLOAD_SECRET. On a live site alsoNEXT_PUBLIC_SERVER_URL, or links and SEO tags point athttp://localhost:3000. - Everything else is optional. Without a service's variables, that service is off and the rest of the site works as before.
- Read when the server starts, in the Docker image as well. Nothing is baked into the build: one image runs anywhere.
The table below is made from .env.example by pnpm docs:env. Run it after changing .env.example; a test fails while the two list different variables.
| Variable | In .env.example | What it does |
|---|---|---|
DATABASE_URL | mongodb://127.0.0.1:27017/tolk | The database: MongoDB or Postgres, picked by the scheme (mongodb://, mongodb+srv://, postgres://, postgresql://). docker compose up -d starts a MongoDB that matches the first value; docker compose up -d postgres starts a Postgres that matches the second. See "Database" in the README. |
PAYLOAD_SECRET | Secret used to sign auth tokens. Generate one with: openssl rand -hex 32 | |
NEXT_PUBLIC_SERVER_URL | http://localhost:3000 | The site's public address, used for canonical URLs, hreflang and SEO previews. Defaults to http://localhost:3000; on Vercel, to the production domain (or a preview's own address) that Vercel sets. |
BLOB_READ_WRITE_TOKEN | Uploaded files (optional). Without it they are written to the uploads folder, which needs a disk that survives a restart (a volume in Docker). With a Vercel Blob store's token they go to Blob instead: what a platform without a disk, such as Vercel, needs. Connecting a Blob store to a Vercel project sets it. See docs/developers/deploy/vercel.md. | |
SMTP_HOST | Email (optional). Form notifications and password resets are sent through this SMTP server. Without SMTP_HOST nothing is sent: Payload writes each email to the console instead. | |
SMTP_PORT | 587 | 587 (STARTTLS) unless your server says otherwise; 465 uses TLS throughout. |
SMTP_USER, SMTP_PASS | Login for the SMTP server. Leave empty if it needs none. | |
SMTP_FROM | The sender address. Required when SMTP_HOST is set. | |
SMTP_FROM_NAME | The sender name. Defaults to "Website". | |
VIMEO_ACCESS_TOKEN | Optional. A Vimeo access token (scopes: public, private, video_files) from an account with access to its videos' files. With it, Vimeo videos play in the site's own player with their subtitles; without it, they play in Vimeo's embedded player. | |
MAILCHIMP_API_KEY, MAILCHIMP_AUDIENCE_ID | Optional. Newsletter sign-ups through Mailchimp: a form ticked "Add sign-ups to the newsletter list" (Forms → Forms) also sends each new submission's email address and name to this audience. Without both values nothing is sent anywhere and the tick box is hidden; submissions are stored either way. The key is under Account → Extras → API keys, the audience id under Audience → Settings → Audience name and defaults. | |
MAILCHIMP_DOUBLE_OPT_IN | Set to true to have Mailchimp ask new subscribers to confirm by email (double opt-in). Otherwise they are subscribed at once. | |
ANTHROPIC_API_KEY | Optional. An Anthropic API key (console.anthropic.com) for AI translation: the Translate, Proofread and Copy desk buttons, the Glossary and the Translation style guide. The site pays for what it translates on this key. Without it, every AI control is hidden and the AI endpoints answer 404; everything else works as before. | |
MCP_ENABLED | Optional. Set to true to let people connect their own AI assistant (Claude Desktop, Claude Code or any MCP client) to the site's Glossary, Translation style guide and Translation memory, at /api/mcp. Each person turns on an API key under their account; the assistant acts with their role. Without it the endpoint answers 404 and no key works. It needs no ANTHROPIC_API_KEY: the person's own assistant does the translating. | |
JOBS_AUTORUN | Background jobs (optional), such as scheduled publishing. The server runs them itself, once a minute. Set JOBS_AUTORUN=false to stop that: on every container but one when several run at once, or where a cron calls the run endpoint instead (see "Background jobs" in the README). On Vercel it is off by itself, and Vercel Cron calls the endpoint (vercel.json). | |
CRON_SECRET | Lets a cron run the jobs from outside: GET /api/payload-jobs/run?allQueues=true with the header "Authorization: Bearer <CRON_SECRET>". Without it, only logged-in admins may call that. Generate one with: openssl rand -hex 32 | |
MAP_TILES | Optional. Set to off to draw maps (the dealer locator) without their background tiles: markers only, and no visitor's browser asks a tile server. The e2e tests set it, so they never depend on one. The tile server itself is chosen in Site settings -> Maps. | |
TOLK_UPDATES | Optional. Once a day the server reads the public list of Tolk Starter releases, and admins see a card on the dashboard when a newer version is out. It is one plain GET; nothing about the site is sent. Set to off to turn it off. | |
TOLK_UPDATES_URL | Where that list is read from. Defaults to https://tolkhq.com/releases.json. | |
DEMO_ADMIN_EMAIL, DEMO_ADMIN_PASSWORD | Optional. The demo site (pnpm seed:demo, see "Demo content" in the README). The login the seed makes for demo visitors, an editor; without both, it makes none. Use a password of at least 8 characters, and only for the demo: a public demo shows it on its login page. | |
DEMO_RESET | Set to true only where the demo is reset (pnpm seed:demo --reset, or the nightly reset of DEMO_MODE). A reset also needs a database the demo seed filled; it refuses everywhere else. | |
DEMO_MODE | Optional. Set to true to run the site as a public demo that anyone may log in to (see docs/developers/deploy/live-demo.md): a notice on every page, kept out of search engines, the demo login shown on the login page, no email, newsletter or Vimeo calls, small uploads only, and AI only within DEMO_AI_DAILY_LIMIT. With DEMO_RESET=true as well, the site resets itself every night. Never on a real site. | |
DEMO_RESET_AT | The time of the nightly reset, in UTC, as HH:MM. Defaults to 03:00. Set it to your cron's time when a cron resets the demo instead. | |
DEMO_AI_DAILY_LIMIT | AI model calls a demo may make per day (UTC), for the whole site. Defaults to 0: AI is off in a demo, even with ANTHROPIC_API_KEY set. |
Variables for tooling #
These are read by the tests and scripts in the repository, never by the site:
| Variable | Read by | What it does |
|---|---|---|
E2E_DATABASE_URL | pnpm test:e2e | The end-to-end tests' own database. Defaults to mongodb://127.0.0.1:27017/tolk-e2e. See Testing. |
DOCS_DATABASE_URL | pnpm docs:screenshots | The throwaway database the screenshots are taken from. Derived from a MongoDB DATABASE_URL when unset. |
VIDEO_DATABASE_URL | pnpm video:record | The throwaway database the walkthrough is recorded from. Derived from a MongoDB DATABASE_URL when unset. See Recording a product walkthrough. |
NEXT_OUTPUT | pnpm build | standalone builds the self-contained server the Docker image runs. The Dockerfile sets it. |