> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subscriber.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting

> Run the open source community edition on your own servers.

These docs are written for [subscriber.dev cloud](https://subscriber.dev). If you'd rather run the open source community edition yourself, it's free and has no limits. Emails end with a small "Powered by subscriber.dev" line. It's licensed under AGPL-3.0.

## What you'll run

| Service | Purpose |
| - | - |
| `web` | Sign-in, unsubscribe pages and the website |
| `api` | REST API, MCP server and background jobs |
| `postgres` | Database |
| `redis` | Job queue for workflow steps and broadcasts |

## Run it with Docker Compose

```bash theme={null}
git clone https://github.com/kanbn/subscriber.dev.git
cd subscriber.dev
cp .env.example .env
```

Fill in `.env`, then start everything:

```bash theme={null}
docker compose up -d
```

The web container runs database migrations when it starts.

`GET /health` on the API returns `200` when it can reach Postgres and Redis, and `503` when it can't. Docker Compose uses it as the API's healthcheck, and you can point an uptime monitor at it.

## Configuration

These settings go in `.env`.

| Variable | Required | Description |
| - | - | - |
| `NEXT_PUBLIC_BASE_URL` | Yes | Public URL of the web app |
| `NEXT_PUBLIC_API_BASE_URL` | Yes | Public URL of the API |
| `MCP_URL` | No | Public URL of the MCP server, if it's on its own host (e.g. `https://mcp.acme.com`). Defaults to the API URL plus `/mcp`. Set it on the API and the web app |
| `BETTER_AUTH_SECRET` | Yes | Random secret for sessions. Generate with `openssl rand -base64 32` |
| `EMAIL_UNSUBSCRIBE_SECRET` | Yes | Random secret that signs unsubscribe links |
| `INTEGRATIONS_ENCRYPTION_KEY` | Yes | Encrypts provider credentials at rest. Generate with `openssl rand -base64 32` |
| `POSTGRES_PASSWORD` | With Compose | Password for the bundled Postgres |
| `POSTGRES_URL` | With your own database | Connection string for an external Postgres |
| `REDIS_HOST`, `REDIS_PASSWORD` | Yes | Redis connection |
| `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` | For image uploads | Any S3-compatible storage, such as Cloudflare R2 or MinIO |
| `S3_REGION` | No | The bucket's region. Defaults to `us-east-1`, which works for R2 and MinIO |
| `ASSETS_BUCKET`, `ASSETS_URL` | For image uploads | The bucket to upload to, and the public URL it's served from. Without these, uploads are turned off and you can still use image links |
| `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `EMAIL_FROM` | For sign-in | Sends sign-in links. This is separate from the providers your workflows send through |
| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | No | Enables GitHub sign-in |

## Point the CLI and MCP at your server

```bash theme={null}
subscriber login --base-url https://api.yourdomain.com --app-url https://yourdomain.com
```

The browser opens your web app to sign in. The first time, you get an email link, sent with the `SMTP_` settings above, or you can sign in with GitHub if you set it up. That creates your account. Then create a workspace, which comes with a **Production** environment:

```bash theme={null}
subscriber workspaces create "Acme"
```

For MCP, use `https://api.yourdomain.com/mcp` as the server URL.

## Upgrade

```bash theme={null}
git pull
docker compose up -d --build
```

Database migrations run when the web container starts.

## Back up

Everything lives in Postgres. To take a backup:

```bash theme={null}
docker compose exec postgres pg_dump -U subscriber subscriber_db > backup.sql
```

To restore it into an empty database:

```bash theme={null}
docker compose exec -T postgres psql -U subscriber subscriber_db < backup.sql
```

Redis only holds the job queue. Losing it can drop steps that were waiting to run, but no data.

## Business license

A self-hosted Business license removes subscriber.dev branding and includes priority support. Enterprise licenses cover AGPL exemptions. Email [sales@subscriber.dev](mailto:sales@subscriber.dev).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.