Self-hosting

Self-hosting is two files (docker-compose.yml and .env) plus docker compose up -d. Both files live in the Customermates repo and you fetch them with curl. No git clone, no build step. The published image at ghcr.io/customermates/customermates:latest runs migrations on first boot and ships ready to use.

Self-host vs cloud

Both have the same feature set.

Data custody: Cloud stores data in our EU region, GDPR-compliant, with the usual encryption-at-rest and in-transit. If your compliance posture requires data on your own infra, self-host.

Cost shape: Cloud is predictable per-seat and scales linearly. Self-host is free for the core plus whatever you pay for infra (a small VPS handles hundreds of users). For a 5-person team, cloud is usually cheaper once you factor in the time to run Postgres backups yourself. For a 50-person team, self-host pays off quickly.

You can migrate between them. Export from one, import to the other. The data model is identical. No lock-in either direction.

Install

Prerequisites

• Docker and Docker Compose v2.
• A domain name if you want TLS (optional for local).
• ~2 GB RAM and a couple of GB of disk per thousand records.

1. Create a directory and fetch the two config files

mkdir customermates && cd customermates
curl -fsSL https://raw.githubusercontent.com/customermates/customermates/main/docker-compose.yml -o docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/customermates/customermates/main/.env.selfhost.template -o .env

Then edit .env with real values:

• BETTER_AUTH_SECRET: a long random string (openssl rand -hex 32).
• CRON_SECRET: another long random string. The webhook-worker sidecar uses this to authenticate against /api/cron/webhook-deliveries. Mismatch means webhooks pile up in pending forever.
• POSTGRES_PASSWORD: change the default.
• BASE_URL: your public URL (e.g. https://crm.example.com). Defaults to http://localhost:4000 for local.
• RESEND_API_KEY and RESEND_FROM_EMAIL: required for signup verification, password reset, and invitation emails.

2. Start

docker compose up -d

First boot takes a minute while Prisma applies migrations. Watch the logs:

docker compose logs -f app

When the app is ready, open http://localhost:4000 (or your custom APP_PORT).

3. First account

Open the URL. Sign up with your email, click the verification link from the inbox, then choose a workspace name. Manage roles for additional users from Company → Users and Company → Roles.

4. Reverse proxy and TLS

Point your reverse proxy (Caddy, nginx, Traefik) at the app port (4000 by default, or your custom APP_PORT). Caddy example:

crm.example.com {
  reverse_proxy localhost:4000
}

Customermates sets secure cookies when BASE_URL uses https://. Make sure the proxy forwards X-Forwarded-Proto correctly.

5. Create an API key

Profile → API Keys → New key. Same flow as cloud. See API keys.

Day-to-day operations

Update

docker compose pull
docker compose up -d

Pulls the latest app image and restarts the affected services. Migrations run automatically on container boot. Verify with docker compose ps.

Restart

docker compose restart

Restarts the stack without pulling a new image. Use after .env changes.

Logs and troubleshooting

docker compose logs -f app
docker compose logs -f postgres
docker compose logs -f webhook-worker
docker compose ps
docker compose exec app sh

The webhook-worker container stays quiet on success and prints any non-2xx response ([webhook-worker] HH:MM:SSZ cron returned 401). If you see those lines, the worker's CRON_SECRET doesn't match the app's, or the cron route is otherwise unreachable. If deliveries are stuck pending and the worker logs are empty, the worker is healthy.

Reset all data

docker compose down -v
docker compose up -d

-v deletes the Postgres volume. IRREVERSIBLE. Take a backup first if you need the data.

Backups

Back up Postgres with pg_dump on a schedule. The app container is stateless.

docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" \
  | gzip > /var/backups/customermates-$(date +%Y%m%d).sql.gz

For production:

• Schedule daily dumps to a separate volume or off-site storage.
• Test restore procedures in a non-production environment.
• Keep .env and secrets out of source control.

Enterprise features

Audit Logging, SSO, and White-labeling require an Enterprise license. Everything else is free. Configure the license per the instructions shipped with your license key.

Next

• Architecture and security: what you're running.
• API keys: key hygiene.
• Connect your AI: once installed, point an MCP client at your instance.