Self-hosting

Consultainer is self-hosted only: no billing, no plan limits, no telemetry. It ships as a multi-arch (amd64/arm64) image at ghcr.io/armistice-group/retainer and runs from one Docker Compose file with four services:

You need a Linux, macOS or Windows host with Docker Engine and the Compose plugin (docker compose version should work), about 1 GB of free RAM, and openssl to generate secrets.

Install

1. Download the compose file and settings template

   In an empty directory (for example ~/consultainer):

   curl -O https://raw.githubusercontent.com/Armistice-Group/retainer/main/docker-compose.yml
   curl -o .env https://raw.githubusercontent.com/Armistice-Group/retainer/main/.env.example

   Copy

2. Generate the three required secrets

   Run each command and paste its output after the matching = in .env:

   openssl rand -base64 32   # → AUTH_SECRET
   openssl rand -base64 32   # → INTEGRATION_ENCRYPTION_KEY
   openssl rand -hex 32      # → CRON_SECRET

   Copy

   INTEGRATION_ENCRYPTION_KEY must be base64 that decodes to exactly 32 bytes, which is what openssl rand -base64 32 produces. Don't use a hex value or a password for it.

   Save a copy of INTEGRATION_ENCRYPTION_KEY somewhere outside this server (a password manager). It encrypts SSO client secrets, integration credentials and tokens, and calendar links. If you lose it, a database backup can't decrypt them, and every integration, SSO connection and calendar has to be set up again.

3. Set a database password

   Change POSTGRES_PASSWORD=change-me to a long random value, for example the output of openssl rand -hex 24. Leave POSTGRES_USER and POSTGRES_DB as they are unless you have a reason to change them.

   Postgres only reads these values the first time it creates the db_data volume. Changing them later doesn't change the database; see Troubleshooting.

4. Set a setup token if the server is reachable from the internet

   Until someone completes first-run setup, whoever opens the app first can create the owner account. If the host is public, set a token that the setup page will ask for:

   openssl rand -hex 16      # → SETUP_TOKEN

   Copy

5. Start it

   docker compose up -d
   docker compose logs -f consultainer-app

   Copy

   Wait for Running database migrations... followed by Starting server, then press Ctrl+C to stop following the log (the app keeps running).

6. Open the app and create your workspace

   Go to http://<this-host>:3113 (or your APP_PORT). A new database sends every page to /setup. Fill in:

   • Setup token: the SETUP_TOKEN value (only shown if you set one).
   • Organization name: your company's name.
   • Instance URL: pre-filled with the address in your browser. This is the address used in links that get sent to people (invites, client invoice links, share and review links, emails). If people will reach the app at a different address, such as a domain you'll put a reverse proxy in front of later, enter that instead. Not shown when AUTH_URL is set.
   • Your name, Email and Password (at least 10 characters, with a letter and a number). This becomes the organization's Owner.

   Click Create workspace. You're signed in and taken to a checklist (/welcome) with next steps: single sign-on, inviting your team, adding a client, and integrations. The Quickstart walks through them.

Check it worked: docker compose ps lists all four services as running, and opening /setup again now redirects to the login page. Setup can only be completed once; after the first account exists, /setup is closed for good.

Try it with demo data

To look around with realistic sample data, run this before completing /setup (it needs an empty database):

docker compose exec consultainer-app node_modules/.bin/tsx prisma/seed-demo.ts

Then sign in as maya@northwind.example / password123. Don't do this on an instance you plan to use for real: to start over, run docker compose down -v (this deletes the database) and docker compose up -d.

Build from source instead of pulling the image

From a checkout of the repository:

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Settings (.env)

Every variable is described in .env.example. After changing .env, run docker compose up -d again so the containers pick up the change (a plain restart does not re-read .env).

Required

docker compose refuses to start without the first three (it prints Set AUTH_SECRET in .env ... and so on).

Recommended

Optional

You can leave every integration variable out. The Owner can enter the same credentials in the app, under Settings → Integrations and Settings → Payments, and those cards show the exact callback and webhook URLs to register. A variable set in .env takes precedence over anything saved in the app and shows as read-only there.

Put it behind a domain with HTTPS

For anything beyond a LAN, put a reverse proxy with TLS in front of the app. The app needs to know the address the browser used, so the proxy must pass these headers:

Both examples below assume the app is published on 127.0.0.1:3113 on the same host (set APP_PORT=127.0.0.1:3113 in .env and run docker compose up -d).

time.example.com {
	reverse_proxy 127.0.0.1:3113
}

server {
    listen 443 ssl;
    http2 on;
    server_name time.example.com;

    ssl_certificate     /etc/letsencrypt/live/time.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/time.example.com/privkey.pem;

    # Uploads can be up to 25 MB with object storage; nginx's default is 1 MB.
    client_max_body_size 30m;

    location / {
        proxy_pass http://127.0.0.1:3113;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        # The MCP server streams responses.
        proxy_buffering off;
    }
}

server {
    listen 80;
    server_name time.example.com;
    return 301 https://$host$request_uri;
}

Caddy gets a certificate automatically and already sends the right headers. Traefik also sends them by default.

Then:

1. Update the instance URL

   Sign in as the owner on the new address, open Settings → General, and in the Instance URL card click Use this address (or type the URL) and Save.

2. Re-register callback URLs

   Redirect and webhook URLs you registered with other services (SSO, Google sign-in, Linear, QuickBooks, Stripe, file services) contain the old address. Each settings card shows the current one; update them in the provider's console.

Check it worked: the app loads over https://, you can sign out and back in, and Settings → Security shows a redirect URI starting with https://time.example.com.

URLs

Consultainer uses two kinds of address:

• Redirects the browser follows straight away (sign-in, SSO, OAuth connections, passkeys, pay links) use whatever address the request came in on. So the app works at localhost, a LAN name and a public domain at the same time.
• Links that leave the browser (emails, invite links, client invoice and share links, contractor review links, webhook URLs) use the instance URL. It's set at /setup and only the Owner can change it, under Settings → General → Instance URL. These links never trust the request's Host header, so a forged header can't put another domain into an email.

Set AUTH_URL (for example AUTH_URL=https://time.example.com) only if you want to force one address for both. It then replaces the instance URL, and the setting in the app becomes read-only.

Behind an authenticating proxy

If something in front of the app requires a login (Cloudflare Access, oauth2-proxy, an SSO gateway), let these paths through without it. Each has its own authentication or is meant to be public:

Scheduled jobs

The scheduler service waits 60 seconds after it starts, then calls these endpoints on the app with Authorization: Bearer <CRON_SECRET>. Every job is idempotent: running one twice never sends or creates anything twice.

The daily job runs on the scheduler's first pass and then every 24 hours, so its time of day is whenever the scheduler last started. Restarting the scheduler runs it again straight away, which is harmless.

To check the jobs work, run one by hand:

docker compose exec scheduler sh -c 'curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://consultainer-app:3000/api/cron/recurring-invoices'

You should get JSON back (for example {"ran":0,...}). {"error":"Unauthorized"} means the scheduler's CRON_SECRET doesn't match the app's; run docker compose up -d to recreate both from the same .env.

Running the app some other way (Kubernetes, a PaaS, systemd)? Send a POST to the same endpoints on the same schedule with the same header.

File storage

Uploaded files (client and project documents, expense receipts, milestone and time entry evidence) are stored in the database by default, up to 5 MB each. To keep them in S3-compatible object storage instead (AWS S3, Cloudflare R2, MinIO, Backblaze B2, Wasabi and others), with a 25 MB limit per file:

1. Create a private bucket

   Create a bucket (for example consultainer) and leave public access off. Consultainer reads files back itself and serves them behind its own access checks; nothing in the bucket is ever made public.

2. Create an access key for it

   Create a key that can read, write, delete and list objects in that bucket, and note the access key ID and secret.

   • AWS S3: an IAM user with a policy allowing s3:GetObject, s3:PutObject, s3:DeleteObject on arn:aws:s3:::consultainer/* and s3:ListBucket on arn:aws:s3:::consultainer, then an access key for that user. If the app runs on EC2 with an instance role, you can leave the key variables out and the role is used.
   • Cloudflare R2: R2 → Manage R2 API Tokens → Create API token with Object Read & Write on the bucket. Use the S3 endpoint shown for your account.
   • MinIO: create an access key in the MinIO console with a policy for the bucket.

3. Add the S3 settings to .env

   S3_BUCKET=consultainer
   S3_REGION=us-east-1          # R2: auto
   S3_ENDPOINT=                 # empty for AWS; R2: https://<account-id>.r2.cloudflarestorage.com; MinIO: http://minio:9000
   S3_ACCESS_KEY_ID=...
   S3_SECRET_ACCESS_KEY=...
   S3_FORCE_PATH_STYLE=false    # true for MinIO and most self-hosted servers
   S3_PREFIX=                   # optional, e.g. consultainer/ to share a bucket

   Copy

4. Apply it

   docker compose up -d

   Copy

5. Check it worked

   Open Settings → Integrations and find the File storage card. It should say Uploads go to the consultainer bucket (S3-compatible), up to 25MB each and The bucket is reachable. If it says Can't reach the bucket followed by an error name, check the endpoint, region, keys and S3_FORCE_PATH_STYLE.

6. Move existing files (optional)

   New uploads go to the bucket from now on. Files already in the database keep working where they are. To move them into the bucket too:

   # Count what would move, without changing anything
   docker compose exec consultainer-app node_modules/.bin/tsx scripts/move-files-to-object-storage.mts --dry-run
   
   # Move them
   docker compose exec consultainer-app node_modules/.bin/tsx scripts/move-files-to-object-storage.mts

   Copy

   It prints In the database: N documents, N receipts, N evidence files. and, after moving, Moved N files to <bucket>. Each file's database copy is cleared once it's in the bucket. It's safe to run again; it only touches files still in the database.

Documents linked from Google Drive, Dropbox, OneDrive or Notion are never stored by Consultainer, so they don't use storage at all.

Email

Email is optional. Without it:

• invites and contractor review requests give you a link to share yourself;
• Email me a login link instead on the login page is hidden;
• email address changes apply right after a password check, without a confirmation email;
• emailing invoices to clients, overdue reminders, email alerts and the weekly digest are off. Invoices can still be shared with Copy client link.

To turn it on, the owner picks Resend or SMTP (Postmark, SES, Mailgun, Google Workspace, your own server…) on the welcome page after setup, or later under Settings → Integrations → Email. It can also be set in .env; see Email. Send a test email checks it end to end and shows the service's reason if it fails.

Google sign-in

Continue with Google on the login page is optional. The owner turns it on under Settings → Integrations → Google sign-in (or with AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env, which wins over the settings):

1. In the Google Cloud console, pick or create a project and set up Google Auth Platform (Audience: Internal for one Google Workspace, otherwise External, published).
2. Create a client of type Web application with the redirect URI the card shows: <your URL>/api/auth/callback/google.
3. Paste its client ID and secret on the card and save. The login page shows the button straight away.

Google sign-in never creates accounts on its own: a new Google user gets in only with an invite or through an organization's auto-join domain.

Upgrading

docker compose pull
docker compose up -d
docker compose logs -f consultainer-app

The app applies any new database migrations when it starts (Running database migrations... in the log). Migrations only go forward: to go back to an older version after an upgrade, restore the backup you took before it. So take a backup before upgrading.

The running version is shown at the bottom of the sidebar.

Pinning a version

CONSULTAINER_VERSION in .env picks the image tag:

To upgrade on your own schedule, set an exact release (for example CONSULTAINER_VERSION=0.2.0), then change it and run the upgrade commands when you're ready. Release notes are on the repository's releases page.

Backups

Back up three things:

1. The database. The backup service does this for you every night. Without object storage, the database also holds every uploaded file, so the dump includes them.
2. Your .env, above all INTEGRATION_ENCRYPTION_KEY. A database backup restored with a different key loses every SSO, integration and calendar credential. Keep a copy somewhere other than this server, such as a password manager.
3. The bucket, if you use object storage. Uploads in the bucket are not in the database dump. Use your provider's versioning or replication, or copy the bucket with a tool like rclone.

What runs

The backup service in docker-compose.yml is on by default. Every night at BACKUP_HOUR (UTC) it runs pg_dump against the app's database and writes a compressed custom-format dump named like consultainer-20261010T030000Z.dump. It keeps the newest BACKUP_KEEP dumps and deletes older ones. A dump is written under a temporary name first, so a failed run never replaces a good backup. It's safe while the app is running.

Set them in .env, then run docker compose up -d. Passwords are passed through the environment and are never written to the log.

Check it worked: run a backup now and list what's there.

docker compose exec backup backup-now
docker compose exec backup ls -lh /backups

You should see backup: wrote consultainer-....dump (...). The service's log (docker compose logs backup) starts with backup: nightly at 03:00 UTC to /backups, keeping 14 and records every run.

Where the files are

By default the dumps live in the backups Docker volume. To copy one out to the current directory:

docker compose cp backup:/backups/consultainer-20261010T030000Z.dump .

With BACKUP_DIR set, they're plain files in that folder, readable only by root (they contain your data, including password hashes and encrypted credentials).

Copy backups off the server

A backup on the same disk doesn't help if the server is lost. Either copy the dump files elsewhere yourself, or let the service upload them to the S3-compatible bucket you set up for file storage:

1. Set the S3 variables

   Fill in S3_BUCKET, S3_REGION, S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and S3_FORCE_PATH_STYLE in .env as described in File storage. The key needs to list, write and delete objects in the bucket.

2. Turn on the upload

   Add BACKUP_S3=true to .env and run docker compose up -d.

3. Run a backup

   docker compose exec backup backup-now

   Copy

   You should see backup: copied consultainer-....dump to s3://<bucket>/backups/.

Dumps go under backups/ in the bucket (after S3_PREFIX, if you set one), and the bucket also keeps only the newest BACKUP_KEEP. The upload uses rclone, which the service installs the first time it needs it. To keep backups for longer than that, use a separate bucket with versioning or object lock, or copy them elsewhere.

Turn it off

Set BACKUP_ENABLED=false in .env and run docker compose up -d. The service stays up but idle (its log says backup: nightly backups are off), and backup-now and restore still work by hand. Turn it off if you back up Postgres another way, for example with snapshots of the whole server.

Restore

Restore into the same version of Consultainer you backed up from, or a newer one. Use the same INTEGRATION_ENCRYPTION_KEY as the original instance.

1. Stop the app and scheduler

   docker compose stop consultainer-app scheduler

   Copy

   Leave consultainer-db and backup running. On a new server, copy over docker-compose.yml and the original .env, then run docker compose up -d consultainer-db backup.

2. Put the dump where the backup service can read it

   Restoring a nightly backup on the same server? Skip this step. To list what's there, run docker compose exec backup restore.

   For a dump from somewhere else (your bucket, another machine), copy it in:

   docker compose cp consultainer-20261010T030000Z.dump backup:/backups/

   Copy

   With BACKUP_DIR set, you can instead put the file in that folder.

3. Restore it

   docker compose exec backup restore consultainer-20261010T030000Z.dump --yes

   Copy

   This deletes the current database, creates an empty one and loads the dump into it. You should see restore: done. If the file isn't a valid dump, it stops before deleting anything.

4. Start everything

   docker compose up -d

   Copy

   The app applies any migrations newer than the backup on start.

Check it worked: you can sign in with an existing account, your recent clients and invoices are there, and Settings → Integrations shows your integrations as connected rather than asking for credentials again (if it asks, the encryption key doesn't match).

docker compose exec -T consultainer-db sh -c 'dropdb -U "$POSTGRES_USER" --force --if-exists "$POSTGRES_DB" && createdb -U "$POSTGRES_USER" "$POSTGRES_DB"'
docker compose exec -T consultainer-db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < consultainer.sql

Troubleshooting

docker compose exec consultainer-app node -e 'console.log(require("bcryptjs").hashSync(process.argv[1], 12))' 'a-new-long-password1'

docker compose exec consultainer-db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

UPDATE "User" SET "passwordHash" = '<hash from above>', "sessionVersion" = "sessionVersion" + 1 WHERE email = 'you@example.com';
-- only if needed:
UPDATE "User" SET "twoFactorEnabled" = false, "twoFactorSecret" = NULL, "twoFactorRecoveryCodes" = '{}' WHERE email = 'you@example.com';