Environment variables

Where the settings live

Create each app's file from the .env.example beside it, which documents every variable: cp .env.example .env. The examples work as they are for a local run, and the Docker Compose start needs no file at all.

Where the settings live

One file, .env in the website's folder, and every value in it is optional. The NEXT_PUBLIC_* values are read when the website is built and are public, so they never hold a secret; API_INTERNAL_URL is read by the website's own server. Without the file, the site runs on its built-in sample data. To use an API, create it from .env.example, which points at one on http://localhost:8000: cp .env.example .env. With Docker, pass the NEXT_PUBLIC_* values as --build-arg and API_INTERNAL_URL with -e.

Where the settings live

One file, .env in the dashboard's folder, read when the dashboard is built and, for PORT, when yarn dev or yarn start begins. Every value in it is public, so it never holds a secret: provider and payment keys live in the API's .env. Without the file, the dashboard runs on its built-in sample data. To use an API, create it from .env.example, which points at one on http://localhost:8000: cp .env.example .env. With Docker, pass the same values as --build-arg.

Where the settings live

One file, .env in the API's folder, read by the API with yarn dev, yarn start:prod and yarn seed. It holds secrets: never commit it. Create it from .env.example, which documents every variable and works as it is for a local run: cp .env.example .env.

The Docker image sets its own defaults, so docker run works without a file: NODE_ENV=production, SQLite at /data/database.sqlite, uploads in /data/uploads, CORS_ORIGIN for the two local frontends, FRONTEND_URL and DASHBOARD_URL set to http://localhost:3031, WEBSITE_URL=http://localhost:3030, PUBLIC_API_URL=http://localhost:8000 and PUBLIC_MEDIA_URL=http://localhost:8000/media. Override any of them with -e.

API essentials

The API checks JWT_SECRET and, in production, CORS_ORIGIN before it starts. If one is missing or unusable, it stops with one line beginning The API cannot start: that says what to fix.

Generate your own JWT_SECRET with:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Every optional feature below is off while its variables in .env.example stay empty.

Payments

Two flows take money. The dashboard's Billing page changes a workspace's subscription plan, and the website's checkout sells the licences. Both take card details only on Stripe's or PayPal's own page (a plan upgrade is charged to the card Stripe already holds), so they are never typed on your site, and both work with no account at all through built-in test checkouts that charge nobody. Use test keys first: they move no money.

STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secret
BILLING_PROVIDER=
BILLING_GRACE_DAYS=7
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-client-secret
PAYPAL_ENV=sandbox

On your own computer Stripe cannot reach the webhook, so the return pages ask Stripe for the session themselves and a test payment still completes. A plan or a licence counts as paid only once the API has verified it with the provider, never from the return address alone. Northstack charges no tax by itself, so set up tax for your country before taking real payments.

• Subscription billing
• The licence checkout

Email

Invitations, password resets, licence receipts, the billing emails and the weekly digest are sent over SMTP once SMTP_HOST is set, each in the recipient's language (the workspace's when they have chosen none). Until then every message is written to the API's log instead, links included, so a local install can follow them (with Docker: docker compose logs api).

SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-secret
SMTP_FROM=Northstack <no-reply@your-domain.com>
CONTACT_INBOX=hello@your-domain.com

SMTP_SECURE=true is for a server that speaks TLS from the first byte, usually on port 465. CONTACT_INBOX is where the website's contact form messages are forwarded; empty keeps them in the database only.

Use MySQL instead of SQLite

Create an empty database, then set the driver and the connection in the API's .env:

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your-database-secret
DB_DATABASE=northstack

Then run yarn seed, which creates the tables and the sample data. The running API only creates and updates the tables itself when NODE_ENV=development, so with NODE_ENV=production run yarn admin:create:prod once after yarn build for the tables and your first Platform admin (yarn seed:prod for a sample install), and yarn schema:prod after each update. The Docker image creates the database by itself on SQLite only: on MySQL, run node dist/database/create-admin.js (or node dist/database/seeder.js) once in the container yourself.

Uploads and media

The API serves the kit's brand files itself at /media. Project files and pictures uploaded from the dashboard, up to 10 MB each, are stored on the API's disk under MEDIA_UPLOAD_DIR and served at /media/uploads/…, unless a bucket is set.

PUBLIC_MEDIA_URL=http://localhost:8000/media
MEDIA_UPLOAD_DIR=./public/media/uploads

PUBLIC_MEDIA_URL is the address /media is reached at from a browser. On a server, point MEDIA_UPLOAD_DIR at persistent storage; with Docker it is in the data volume, and the container moves a relative folder there by itself. The API sends every file there with nosniff, and a file that is not a picture, a PDF, plain text, audio or video as a download.

To send uploads to a Cloudflare R2 bucket, set all five variables. With fewer than five, uploads stay on the disk. The API's log names the storage it uses when it starts: Media storage: R2 bucket followed by the bucket's name, or Media storage: local folder followed by the folder.

R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=your-bucket-name
R2_PUBLIC_URL=https://your-public-url.r2.dev

Website and dashboard

Every NEXT_PUBLIC_* value is compiled into the JavaScript the browser loads, and anyone who opens the page can read it. Never put a secret in one, and rebuild (or restart yarn dev) after changing one. With Docker, pass them as --build-arg.

NEXT_PUBLIC_API_BASE_URL decides where each frontend's data comes from. Empty, or with no .env at all, the app runs on its built-in sample data and calls no API. Set to the API's address including /api (http://localhost:8000/api in .env.example and in the Docker images), it uses that API, and stands in with the sample data in the browser only while that API does not answer.

• The sample data

The website's settings

The website's port is 3030, written in its package.json scripts. For another, run yarn next dev -p 3040 (or yarn next start -p 3040 after yarn build).

The dashboard's settings

No AI provider or payment key belongs here: a NEXT_PUBLIC_* value is visible to anyone who opens the page. A provider the API has no key for can still be used with a key the reader adds in the assistant itself.

Docker Compose options

Nothing has to be set for a local run. To change something, put it in a .env file beside docker-compose.yml and run docker compose up --build again: the frontends compile these values in.

Change a port when another program already uses it, such as ADMIN_PORT=3041. The API's CORS_ORIGIN, FRONTEND_URL, DASHBOARD_URL, WEBSITE_URL, PUBLIC_API_URL and PUBLIC_MEDIA_URL, and the frontends' API, website and dashboard addresses, are all built from the ports and the three addresses, so they follow by themselves.

• A port is already in use

The API container also reads back-end/.env when it exists, so the optional keys (Stripe, PayPal, mail, R2, AI, MCP) are set in one place for both yarn dev and Docker. docker-compose.yml wins for the values that differ inside a container: NODE_ENV=production, the port, the database path, the upload folder and the addresses above. Without a JWT_SECRET of your own, or with the example one, the API generates one and keeps it in the data volume. The database and the uploads live in the northstack-data volume.

AI assistant keys

The MCP server

Demo mode