# Configuration reference (/selfhosting/configuring)



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

Required variables [#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. |

<Callout type="warn">
  Changing `SECRET_KEY_BASE` after initial setup will invalidate all stored API keys — users will
  need to re-enter them.
</Callout>

Database [#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 [#using-an-external-database]

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

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

```bash
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:

```bash
docker compose exec app npx prisma db push
```

Redis [#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 [#using-an-external-redis]

To connect to an existing Redis instance:

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

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

Networking [#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:

```yaml
mariadb:
  ports:
    - '3307:3306'

redis:
  ports:
    - '6379:6379'
```

Email (SMTP) [#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 [#example-configurations]

**Gmail / Google Workspace:**

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

<Callout type="info">
  Gmail requires an [App Password](https://myaccount.google.com/apppasswords) if you have 2FA
  enabled (which you should).
</Callout>

**Amazon SES:**

```bash
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):**

```bash
SMTP_MOCK=true
```

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

Application settings [#application-settings]

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

Connections (Settings > Connections) [#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](https://platform.openai.com/api-keys)           |
| Anthropic     | [platform.claude.com/settings/keys](https://platform.claude.com/settings/keys) |
| Google Gemini | [aistudio.google.com/app/api-keys](https://aistudio.google.com/app/api-keys)   |

Models (Settings > Models) [#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) [#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) [#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 [#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 [#full-envexample]

```bash
# 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
```