Environment variables

Where the settings live

Create each app's file from the .env.example next to it, which documents every variable: cp .env.example .env. The examples work as they are for a local run, except the dashboard's two API addresses, which you fill in to leave the sample data.

Where the settings live

One file, .env in the dashboard's folder, read when the dashboard is built. Every value in it is public, so it never holds a secret. Leave it out to run on the sample data; create it from .env.example when you connect an API: cp .env.example .env.

Where the settings live

One file, .env in the API's folder, read by the API with yarn dev, and by a container when you pass it with --env-file .env. 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.

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 saying what to fix. Variables already set in the environment win over the file.

Generate your own JWT_SECRET with:

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

Any storage or AI credential below still holding its exact .env.example value counts as not set, so the feature it belongs to reports itself off instead of failing on its first call.

Use MySQL instead of SQLite

Create an empty database, then set the driver and the connection in back-end/.env:

DB_TYPE=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USERNAME=your-mysql-username
DB_PASSWORD=your-mysql-password
DB_DATABASE=your-database-name

Then run yarn seed for the demo data, or yarn db:sync for the tables with no data. The running API only creates and updates the tables itself when NODE_ENV=development, so with NODE_ENV=production one of those commands runs before the first start (yarn db:sync:prod or yarn seed:prod after yarn build), and yarn db:sync:prod again after an update that changes the schema. It keeps your data.

The template ships its migration for SQLite only. back-end/src/database/migrations/mysql/README.md has the one command that generates the MySQL one, if you want the API's start-up migrations on MySQL too.

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 this file, and restart or rebuild after changing one.

No AI provider key belongs here. Keys live in the API's .env only.

Docker Compose options

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

The API container also reads back-end/.env when it exists, so storage, AI and MCP keys are set in one place for both yarn dev and Docker. The compose file wins for the values that differ inside a container: NODE_ENV=production, the port, SQLite at /data/database.sqlite, DEMO_MODE=false, CORS_ORIGIN and FRONTEND_URL. Without a JWT_SECRET of your own, the API generates one and keeps it in the data volume. The data lives in the kinora-data volume.

The API's Docker image

The image starts in production on SQLite at /data/database.sqlite, port 8000, with DEMO_MODE=false and SEED_DEMO_DATA=false, and allows browser calls from http://localhost:3030 (CORS_ORIGIN and FRONTEND_URL). Change any of them with -e on docker run, or pass your file with --env-file .env.

• On a fresh volume the container creates the tables, and adds the demo data only with SEED_DEMO_DATA=true. An existing database is left alone.
• Without a JWT_SECRET, or with the example one, it generates a secret and keeps it in /data/.jwt-secret, so sign-ins survive a restart.
• With DB_TYPE=mysql it creates nothing: run node dist/database/sync-schema.js or node dist/database/seeder.js in the container once yourself.

Media storage

Profile pictures, progress photos, group covers and message attachments are uploaded to a Cloudflare R2 bucket, or any S3-compatible one. Set the five variables in back-end/.env and give the dashboard the bucket's public host through NEXT_PUBLIC_MEDIA_HOSTNAME (with Docker Compose, MEDIA_HOSTNAME).

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

Without a bucket, everything the seed writes is an /assets/images/… path that the dashboard serves from its own public/assets folder, so every screen renders with nothing uploaded. Only uploading new files stops working: an upload answers 400 until the bucket is set. Keep public/assets in the dashboard for as long as any row still points at it.

A file is at most 150 MB. The dashboard's uploader sends large files in parts of up to 16 MB through POST /api/helpers/upload-chunk, by itself.

Email

The template ships no mail transport, so no message is ever emailed. The members screen's "resend verification email" answers without sending anything, and the forgot-password and reset-password pages are the screens only: no reset is sent, and the API has no route behind them. Connect your own mail provider, and add the reset routes, before going live if your members need either.

• "Forgot password" sends nothing

AI assistant

MCP server

Demo mode

Going live

Before you deploy anywhere public:

1. Set NODE_ENV=production and a long random JWT_SECRET of your own in back-end/.env.
2. Set CORS_ORIGIN to your dashboard's address, and FRONTEND_URL to the same address.
3. Keep DEMO_MODE=false in the API and NEXT_PUBLIC_DEMO_MODE=false in the dashboard.
4. On an empty database, run yarn build, then yarn db:sync:prod once (or yarn seed:prod for the demo data), then yarn start:prod.
5. Point your host's health check at GET /api/health. It needs no token and is not rate limited.
6. Build the dashboard with NEXT_PUBLIC_API_BASE_URL and NEXT_PUBLIC_WEBSOCKET_BASE_URL at your deployed API.
7. Change the seeded passwords, or start from empty tables.

To drop the demo code entirely, run yarn remove:demo in both apps, on a clean tree: it cannot be undone without version control. yarn remove:mock in the dashboard deletes the sample data.