Deploy
Configuration
Every setting in deploy/.env: required values, sign-in, email, uploads, agents and modules.
All settings live in deploy/.env. Apply a change with docker compose --env-file deploy/.env up -d.
Required
| Setting | Meaning |
|---|---|
APP_URL | The address people use. It must match exactly: sign-in cookies, links in emails and the MCP host check all use it. |
BETTER_AUTH_SECRET | At least 32 random characters. It also encrypts connected-calendar tokens and keys the attendance kiosk PINs, so changing or losing it signs everyone out, breaks calendar connections and invalidates every kiosk PIN. |
POSTGRES_PASSWORD | The bundled database's password. Required, with no default. Letters and digits only. |
Sign-in
| Setting | Meaning |
|---|---|
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Adds Continue with Google. Set the callback URL to APP_URL/api/auth/callback/google. |
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET | Adds Continue with GitHub, with the callback at APP_URL/api/auth/callback/github. |
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID | Adds Continue with Microsoft, with the callback at APP_URL/api/auth/callback/microsoft. The tenant defaults to common. |
TRUSTED_ORIGINS | Other addresses for the same server, such as an IP and a hostname, separated by commas. |
SETUP_TOKEN | A fixed first-run setup code, instead of a random one printed in the log. |
Social sign-in still only admits invited addresses, and needs the server to reach the internet.
Email is optional. Without it, invitations and password resets are shared as links and QR codes. To send them, set both values:
SMTP_URL=smtps://USER:PASSWORD@smtp.example.com:465 # TLS from the first byte
# SMTP_URL=smtp://USER:PASSWORD@smtp.example.com:587 # upgrades with STARTTLS
MAIL_FROM=Knotworking <knotworking@example.com>
- URL-encode special characters in the username and password:
@becomes%40. MAIL_FROMmust be a sender your provider accepts. Without it the fallback is a localhost address that almost every provider rejects.- If sending fails, the invitation is still created and the admin sees the link to share by hand.
File uploads
Attachments go to the uploads Docker volume by default. They are never public: every download goes through the API with the same sign-in and membership checks as the rest of the app. Only PNG, JPEG, GIF and WebP images are shown inline; everything else downloads as a file, so an upload can never run script on your domain.
| Setting | Meaning |
|---|---|
UPLOAD_MAX_BYTES | Largest single file. Default 10485760 (10 MB), at most 1 GiB. |
UPLOAD_STORAGE | Set to s3 to use an S3-compatible bucket (AWS, R2, B2, MinIO) instead of the volume. |
S3_BUCKET, S3_REGION, S3_ENDPOINT | The bucket, its region (auto for R2) and, outside AWS, its endpoint. |
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY | A key limited to that bucket: PutObject, GetObject and DeleteObject. |
Ports and addresses
| Setting | Meaning |
|---|---|
HTTP_PORT | The host port Caddy serves plain HTTP on. Default 3000; use 80 with a domain. |
HTTPS_PORT | The host port for HTTPS. Default 443, published only when HTTPS is on. |
DOMAIN | The domain Caddy gets a certificate for. See HTTPS and proxies. |
DATABASE_URL | Use a hosted database instead of the bundled one. See Database. |
See HTTPS and proxies and Database.
Modules and agents
| Setting | Default | Meaning |
|---|---|---|
KNOTWORKING_MODULES | unset | Which modules this installation runs. See Modules. |
KNOTWORKING_DEFAULT_WORKSPACE | none | The workspace agents use when they don't name one. |
MCP_ALLOWED_HOSTS | from APP_URL | Hostnames accepted in the Host and Origin headers of MCP requests. |
MCP_RATE_LIMIT_PER_MINUTE | 120 | Tool calls per token per minute. 0 turns it off. |
MCP_MAX_BATCH | 10 | Most JSON-RPC calls accepted in one HTTP request. |
API_TOKEN_READ_LIMIT_PER_MINUTE | 600 | Reads the API allows per token per minute. |
API_TOKEN_WRITE_LIMIT_PER_MINUTE | 120 | Writes the API allows per token per minute. |
Rate limits are counted in memory per process, so a restart resets them. More in Agents and MCP.