Get Started

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

Self-hosting uses the Starter entitlement baseline. It includes the core CRM records, views, REST, webhooks and MCP for an external AI client that you select and fund. It does not include connected messaging accounts, the unified inbox, connected calendar view, hosted Mate or hosted AI credits. Paying for another cloud plan does not expand the self-hosted entitlement set.

Self-hosting lets you choose where the application and database run. It does not create a security, compliance, privacy or air-gap guarantee by itself. Your organization remains responsible for configuration, providers, contracts, retention and operating controls.

Compare total operating cost rather than assuming one model is cheaper. Include infrastructure, backups, restore testing, monitoring, updates, incident response and external providers as well as any subscription price.

Customermates exports and imports CRM records as Excel workbooks, one entity type at a time, so a working set can move between systems. A whole-platform migration is still a separately designed and validated project.

Install

Prerequisites

• Docker and Docker Compose v2.
• A domain name if you want TLS (optional for local).

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 configured 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.

Apply configuration changes

docker compose up -d

Reconciles the stack and recreates affected containers when configuration changed. Use it after .env changes. For a simple restart with unchanged configuration, docker compose restart is sufficient.

Logs and troubleshooting

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

Enabled background jobs run in-process through the Postgres-backed worker that starts with the application. There is no separate worker service in the Compose file. Inspect application logs with 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.

mkdir -p backups
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' \
  | gzip > 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.

Edition boundary

Every self-hosted deployment uses Starter entitlements. Connected messaging accounts, the unified inbox, connected calendar view, hosted Mate and hosted AI credits are cloud-only capabilities and are not unlocked in self-hosting by a paid cloud plan. External AI clients remain available through MCP. Review LICENSE and ee/LICENSE.md in the repository for the exact code-license boundary.

The hosted in-app Assistant is cloud-only and remains release-gated. External MCP uses your own AI provider. Enterprise SSO and white-labeling are not implemented in either deployment model.

Next

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