Self-hosting

Self-hosting requires 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 and no build step are needed. The published image at ghcr.io/customermates/customermates:latest applies database migrations on first boot.

Self-host vs cloud

Both run the same core application. The self-hosted build matches the Starter feature set: the full core CRM including audit logging. The unified inbox, calendar sync, enterprise SSO, and white-labeling are Enterprise Edition features (the ee/ components); on the cloud, the inbox and calendar sync come with the Pro tier, SSO and white-label with the Enterprise plan. For a self-hosted deployment that includes them, contact us for an Enterprise Edition agreement. Google and Microsoft OAuth sign-in works in either deployment once you set the provider env vars; without them, self-hosted installs sign in with email.

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 priced per user across tiers, starting at €12/user/month, and scales with your messaging usage. Self-host is free for the core application plus whatever you pay for infrastructure (a small VPS handles hundreds of users). For a small team, cloud is often cheaper once you account for the time to run Postgres backups yourself. For a larger team, self-host is usually the lower cost.

You can migrate between them: export from one, import to the other. The data model is identical.

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

The unified inbox, calendar sync, enterprise SSO, and white-labeling are Enterprise Edition features (the ee/ components). On the cloud they come with the plans: inbox and calendar from Pro, SSO and white-label on Enterprise. The free community self-host build does not include them; audit logging is part of every deployment, self-hosted included. If you need them on your own infrastructure, contact us for an Enterprise Edition agreement. Google and Microsoft OAuth sign-in is part of the core and works self-hosted once you set the provider env vars.

Next

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