Get started
Quickstart
Run Knotworking on your own server with Docker Compose, claim the workspace and invite your team.
Requirements
- A machine with Docker and the Compose plugin: a server in the office, a NAS or a small cloud VM.
- For a team of around 30 with light use, 1 vCPU and 1–2 GB of RAM is plenty.
- For HTTPS, a domain pointing at the server. On a local network, plain HTTP is fine.
Configure
Get the code and copy the example settings.
git clone <repository> knotworking && cd knotworking # [TODO: repository URL]
cp deploy/env.example deploy/.env
Open deploy/.env and set three values. Everything else is optional (see Configuration).
| Setting | What to put |
|---|---|
APP_URL | The exact address your team will type, such as http://192.168.1.20:3000 or https://knot.example.com. Sign-in cookies and email links depend on it. |
BETTER_AUTH_SECRET | The output of openssl rand -base64 32. At least 32 characters. Back it up: losing it signs everyone out. |
POSTGRES_PASSWORD | The output of openssl rand -hex 24. Letters and digits only, because it goes into the database URL as-is. |
Start
docker compose --env-file deploy/.env up -d --build
This builds and starts Caddy, the web app, the API, Postgres and the MCP server. Database migrations run automatically each time the API container starts.
Claim the workspace
A fresh installation has no users. The API prints a one-time setup link in its log. Open it to create the workspace and its owner.
docker compose --env-file deploy/.env logs api | grep setup
# Finish setting up Knotworking: http://192.168.1.20:3000/setup?token=…
Requiring the code from the log means nobody else on the network can claim the installation before you do. Setup only works while there are no users. For a new link, run docker compose restart api, or set your own code with SETUP_TOKEN.
Invite your team
Go to Members, then Invite people. Knotworking is invite-only: there is no public sign-up, and only invited addresses can create an account.
- With email set up, invitations are sent for you.
- Without email, the invite dialog shows a link and a QR code to share. Each link works once and expires after seven days.
Next steps
- Put it on a domain with HTTPS. Calendar sync needs it.
- Connect an agent with a personal API token.
- Schedule backups before the team relies on it.