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).
• 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_OPERATOR_EMAIL: a free Resend project. 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 ps
docker compose exec app sh

Background jobs (webhook deliveries, inbox sync, and message backfill) run in-process via an embedded Postgres-backed worker that starts with the app. There is no external job service to configure. Inspect their progress in the app logs (docker compose logs -f app).

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.