Skip to content

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

SettingMeaning
APP_URLThe address people use. It must match exactly: sign-in cookies, links in emails and the MCP host check all use it.
BETTER_AUTH_SECRETAt 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_PASSWORDThe bundled database's password. Required, with no default. Letters and digits only.

Sign-in

SettingMeaning
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETAdds Continue with Google. Set the callback URL to APP_URL/api/auth/callback/google.
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETAdds Continue with GitHub, with the callback at APP_URL/api/auth/callback/github.
MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_IDAdds Continue with Microsoft, with the callback at APP_URL/api/auth/callback/microsoft. The tenant defaults to common.
TRUSTED_ORIGINSOther addresses for the same server, such as an IP and a hostname, separated by commas.
SETUP_TOKENA 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

Email is optional. Without it, invitations and password resets are shared as links and QR codes. To send them, set both values:

deploy/.env
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_FROM must 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.

SettingMeaning
UPLOAD_MAX_BYTESLargest single file. Default 10485760 (10 MB), at most 1 GiB.
UPLOAD_STORAGESet to s3 to use an S3-compatible bucket (AWS, R2, B2, MinIO) instead of the volume.
S3_BUCKET, S3_REGION, S3_ENDPOINTThe bucket, its region (auto for R2) and, outside AWS, its endpoint.
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEYA key limited to that bucket: PutObject, GetObject and DeleteObject.

Ports and addresses

SettingMeaning
HTTP_PORTThe host port Caddy serves plain HTTP on. Default 3000; use 80 with a domain.
HTTPS_PORTThe host port for HTTPS. Default 443, published only when HTTPS is on.
DOMAINThe domain Caddy gets a certificate for. See HTTPS and proxies.
DATABASE_URLUse a hosted database instead of the bundled one. See Database.

See HTTPS and proxies and Database.

Modules and agents

SettingDefaultMeaning
KNOTWORKING_MODULESunsetWhich modules this installation runs. See Modules.
KNOTWORKING_DEFAULT_WORKSPACEnoneThe workspace agents use when they don't name one.
MCP_ALLOWED_HOSTSfrom APP_URLHostnames accepted in the Host and Origin headers of MCP requests.
MCP_RATE_LIMIT_PER_MINUTE120Tool calls per token per minute. 0 turns it off.
MCP_MAX_BATCH10Most JSON-RPC calls accepted in one HTTP request.
API_TOKEN_READ_LIMIT_PER_MINUTE600Reads the API allows per token per minute.
API_TOKEN_WRITE_LIMIT_PER_MINUTE120Writes 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.