Deployment

Docker

The fastest way to get started. MetricChat uses SQLite by default, so no external database is required.

docker run --pull always -d -p 3000:3000 metricchat/metricchat

To use PostgreSQL, pass the MC_DATABASE_URL environment variable:

docker run --pull always -d -p 3000:3000 \
  -e MC_DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname \
  metricchat/metricchat

Open http://localhost:3000 to begin setup.

To update to the latest release, re-run the same command or explicitly pull the image first:

docker pull metricchat/metricchat

Docker Compose

For production deployments. Includes PostgreSQL and a Caddy reverse proxy with automatic TLS on port 443.

1. Clone the repository:

git clone https://github.com/metricchat/metricchat.git
cd metricchat

2. Create a .env file in the project root:

DOMAIN=your-domain.com
POSTGRES_USER=metricchat
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=metricchat
MC_DATABASE_URL=postgresql+asyncpg://metricchat:your-secure-password@postgres:5432/metricchat
MC_ENCRYPTION_KEY=your-fernet-key

Generate a Fernet encryption key:

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Keep MC_ENCRYPTION_KEY consistent across restarts. If the key changes, all stored credentials become unreadable and users will be logged out.

3. Start services:

docker compose up -d

4. Point your DNS.

Add an A record for your-domain.com pointing to the server's public IP. Caddy will automatically obtain and renew a TLS certificate from Let's Encrypt.

Local Development Without SSL

To run the stack locally without TLS, use the development compose file:

docker compose -f docker-compose.dev.yaml up -d

This starts MetricChat and PostgreSQL on HTTP only, accessible at http://localhost:3000.

Configuration File

MetricChat supports a metricchat.yaml configuration file for settings that do not fit cleanly into environment variables (email verification, OAuth, SMTP, feature flags, and more).

Mount it into the container at /app/metricchat.yaml:

docker run --pull always -d -p 3000:3000 \
  -v $(pwd)/metricchat.yaml:/app/metricchat.yaml \
  metricchat/metricchat

A full reference of available configuration keys is available at metricchat.io/docs/configuration.

Kubernetes / Helm

MetricChat publishes a Helm chart for Kubernetes deployments. It supports:

• A bundled PostgreSQL instance for simple cluster deployments
• External managed databases (e.g., AWS RDS, Aurora) with custom connection strings
• IAM-based authentication for Aurora PostgreSQL
• Custom hostname and TLS configuration

Install with Helm:

helm upgrade -i --create-namespace -n metricchat metricchat metricchat/metricchat

To override default values, pass a values.yaml file:

helm upgrade -i --create-namespace -n metricchat metricchat metricchat/metricchat \
  -f values.yaml

Refer to the chart's values.yaml for the full list of configurable options.

AWS Aurora Integration

For Aurora PostgreSQL, MetricChat supports IAM database authentication. Rather than storing a static password, it generates short-lived authentication tokens (valid for 15 minutes) at connection time.

Prerequisites:

1. Enable IAM database authentication on the Aurora cluster.
2. Create a database user and grant the IAM role:

CREATE USER metricchat;
GRANT rds_iam TO metricchat;

3. Attach an IAM policy to the MetricChat service role granting rds-db:connect for the target cluster and user.

Configure the connection string with IAM token authentication enabled in your Helm values or environment configuration.

Authentication

Google OAuth

To enable Google login:

1. Create an OAuth 2.0 client in the Google Cloud Console.
2. Add your MetricChat domain to the list of authorized redirect URIs:

   https://your-domain.com/api/auth/google/callback

3. Enable the People API for the project.
4. Add the client ID and secret to your metricchat.yaml or environment configuration.

OIDC

MetricChat supports OIDC-compliant providers such as Okta. Configure the issuer URL, client ID, client secret, and desired scopes in metricchat.yaml. PKCE is supported.

Environment Variables

To generate a valid MC_ENCRYPTION_KEY:

python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Updating

For Docker Compose deployments, pull the latest image and restart:

docker compose pull
docker compose up -d

Database migrations run automatically on startup. No manual migration step is required.