Install

Conatus ships as a Docker Compose stack: the app, PostgreSQL, MinIO for attachments, a migration job, an optional admin bootstrap job and a backup timer. You need Docker with the Compose plugin and nothing else.

Public beta

The current release is v0.2.0-beta.3. Pinning that exact version is required because the latest image tag will not be published until the first stable release.

1. Get the Compose file and environment template

mkdir conatus
cd conatus

curl -O https://raw.githubusercontent.com/nojusmorkunas/conatus/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/nojusmorkunas/conatus/main/.env.example

2. Edit your credentials

Open .env. These are the values you must change before the first start. The Compose file refuses to start without the passwords and secrets:

# Pin the current public beta. Change this only when following the upgrade guide.
CONATUS_VERSION=0.2.0-beta.3
CONATUS_PORT=4399
# Safe for a local install or a reverse proxy running on this host.
CONATUS_BIND_ADDRESS=127.0.0.1

POSTGRES_USER=app
POSTGRES_PASSWORD=replace-with-a-long-random-password
POSTGRES_DB=app

AUTH_SECRET=replace-with-a-long-random-secret

S3_ACCESS_KEY=replace-with-a-random-access-key
S3_SECRET_KEY=replace-with-a-long-random-secret-key

# Optional: creates the first administrator on an empty database.
CONATUS_ADMIN_USERNAME=admin
CONATUS_ADMIN_PASSWORD=replace-with-a-long-random-password

Every replace-with-... value above is a placeholder. Compose verifies that required variables exist, but it cannot detect an unchanged placeholder. Replace all of them with unique credentials before you start the stack.

Generate AUTH_SECRET with npx auth secret, or any 32+ byte random string. POSTGRES_PASSWORD ends up inside a connection URL, so keep it URL-safe. Letters, digits, - and _ are always fine.

Keep CONATUS_BIND_ADDRESS=127.0.0.1 when your reverse proxy runs on the same host. Use 0.0.0.0 only when you need port 4399 reachable from another machine, and protect that network path with a firewall.

If you are putting Conatus behind a domain or a reverse proxy, you also need AUTH_URL and PUBLIC_BASE_URL. See Reverse proxy.

The environment reference documents every other variable.

3. Start Conatus

docker compose up -d

Compose pulls the application, operations, PostgreSQL and MinIO images, runs the database migrations, then starts the app. Open http://localhost:4399 and sign in with the administrator credentials from .env.

After the first login

Remove CONATUS_ADMIN_USERNAME and CONATUS_ADMIN_PASSWORD from .env and delete the stopped bootstrap container. The bootstrap job only ever acts on an empty database, but there is no reason to leave a password sitting in a file.

Registration is invite-only by default (REGISTRATION_MODE=invite-only): the first account bootstraps the server and becomes its administrator, and everyone else needs an invite.

Never set CONATUS_DEV_MODE on a server

CONATUS_DEV_MODE=1 disables rate limiting on login, registration, password reset, email resend and error reporting, and opens registration to anyone on the internet. It is not gated on NODE_ENV. Setting it in a production .env is enough to do all of that. It exists for local development only.

Where to go next

• Reverse proxy. Put it on a domain with HTTPS.
• Backups. What the backup service does, and how to restore.
• Upgrading. Moving to a new release.
• MCP server. Let AI agents manage tasks.