Skip to content

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.

terminal
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).

SettingWhat to put
APP_URLThe 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_SECRETThe output of openssl rand -base64 32. At least 32 characters. Back it up: losing it signs everyone out.
POSTGRES_PASSWORDThe output of openssl rand -hex 24. Letters and digits only, because it goes into the database URL as-is.

Start

terminal
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.

terminal
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