Configuration reference

Chathouse is configured through environment variables in your .env file. All variables have sensible defaults except for the two required variables below.

Required variables

These must be set before starting Chathouse. The application will refuse to start without them.

Variable	Description
`SECRET_KEY_BASE`	Master secret from which all application secrets (encryption keys, etc.) are derived. Generate with `openssl rand -base64 32`.
`CLIENT_URL`	Public URL where Chathouse is accessible (e.g. `https://chat.yourdomain.com`). Used for shared chat links, password reset emails, etc.

Changing SECRET_KEY_BASE after initial setup will invalidate all stored API keys — users will need to re-enter them.

Database

Chathouse bundles a MariaDB instance by default. These variables configure it:

Variable	Description	Default
`MARIADB_ROOT_PASSWORD`	Root password for the MariaDB container	`rootpassword`
`MARIADB_DATABASE`	Database name	`chathouse`
`MARIADB_USER`	Database user	`chathouse`
`MARIADB_PASSWORD`	Database user password	`chathouse`

The DATABASE_URL is constructed automatically in compose.yaml from these values. You don't need to set it manually unless you're using an external database.

Using an external database

To connect to an existing MariaDB (or MySQL) instance instead of the bundled one:

Remove (or comment out) the mariadb service from compose.yaml
Remove the mariadb dependency from the app and worker services
Set DATABASE_URL directly in your .env:

DATABASE_URL="mysql://user:password@your-mariadb-host:3306/chathouse"

The database schema is managed by Prisma. On first connection, Chathouse will need the schema pushed:

docker compose exec app npx prisma db push

Redis

Chathouse uses Redis for session storage and BullMQ job queuing. A Redis 7 instance is bundled by default.

Variable	Description	Default
`REDIS_URL`	Redis connection string	`redis://redis:6379` (auto-configured)

Using an external Redis

To connect to an existing Redis instance:

Remove the redis service from compose.yaml
Remove the redis dependency from the app and worker services
Set REDIS_URL in your .env:

REDIS_URL="redis://:password@your-redis-host:6379"

Networking

Variable	Description	Default
`PORT`	Host port the app is exposed on	`80`

The MariaDB and Redis containers are not exposed to the host by default — they're only accessible within the Docker network. This is intentional for security.

If you need direct database access for debugging, you can temporarily add port mappings:

mariadb:
  ports:
    - '3307:3306'

redis:
  ports:
    - '6379:6379'

Email (SMTP)

Email is used for password reset flows. All SMTP variables are optional — if not configured, Chathouse falls back to direct MX delivery (which may land in spam).

Variable	Description	Default
`SMTP_HOST`	SMTP server hostname	(empty — uses direct MX)
`SMTP_PORT`	SMTP server port	`587`
`SMTP_USER`	SMTP authentication username	(empty)
`SMTP_PASSWORD`	SMTP authentication password	(empty)
`SMTP_FROM`	Sender address for outgoing emails	`Chathouse <noreply@example.com>`
`SMTP_MOCK`	Set to `true` to log emails to console instead of sending	`false`

Example configurations

Gmail / Google Workspace:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM="Chathouse <you@gmail.com>"

Gmail requires an App Password if you have 2FA enabled (which you should).

Amazon SES:

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-smtp-user
SMTP_PASSWORD=your-ses-smtp-password
SMTP_FROM="Chathouse <noreply@yourdomain.com>"

Disable email entirely (dev/testing):

SMTP_MOCK=true

Emails will be printed to the container logs instead of being sent.

Application settings

These settings are configured through the Chathouse web UI under Settings, not through environment variables.

Connections (Settings > Connections)

Add API keys for the AI providers you want to use. Keys are encrypted at rest using a key derived from SECRET_KEY_BASE.

Provider	Where to get a key
OpenAI	platform.openai.com/api-keys
Anthropic	platform.claude.com/settings/keys
Google Gemini	aistudio.google.com/app/api-keys

Models (Settings > Models)

After connecting a provider, Chathouse automatically fetches the available models. You can:

Enable/disable individual models
Set favorites for quick access
Give models custom display names

Preferences (Settings > Preferences)

Setting	Description	Default
System prompt	Default instructions prepended to every conversation	(empty)
Chat history	Whether to persist chat history	Enabled
Title generation	How chat titles are generated (`ai` or `first_chars`)	`ai`

Security (Settings > Security)

Two-factor authentication — enable TOTP-based 2FA using any authenticator app (Google Authenticator, Authy, 1Password, etc.)
Password change — update your account password

Docker volumes

Chathouse uses three named volumes for persistent data:

Volume	Contents	Path in container
`mariadb_data`	All database data (users, chats, messages, settings)	`/var/lib/mysql`
`redis_data`	Session data and job queue state	`/data`
`uploads_data`	Uploaded file attachments	`/app/data/uploads`

These volumes persist across container restarts and updates. Use docker compose down -v to delete them (irreversible).

Full `.env.example`

# Master secret (required — generate with: openssl rand -base64 32)
SECRET_KEY_BASE="change-this-to-a-random-string"

# Database (optional — defaults work out of the box with the bundled MariaDB)
MARIADB_ROOT_PASSWORD=rootpassword
MARIADB_DATABASE=chathouse
MARIADB_USER=chathouse
MARIADB_PASSWORD=chathouse

# Public URL where Chathouse is accessible (required)
CLIENT_URL="https://chat.yourdomain.com"

# Port the app is exposed on (default: 80)
# PORT=80

# Email (optional)
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM="Chathouse <noreply@example.com>"
SMTP_MOCK=false

Help us improve Chathouse

Was this page helpful to you?

Learn how to contribute•Report a problem with this content

Help us improve Chathouse

On this page