# Continuwuity for Docker

## Docker

To run Continuwuity with Docker, you can either build the image yourself or pull
it from a registry.

### Use a registry

Available OCI images:

| Registry         | Image                                                                                                                                                       | Notes                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:latest](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest)                 | Latest tagged image.                                                         |
| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:main](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main)                     | Main branch image.                                                           |
| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:latest-maxperf](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest-maxperf) | [Performance optimised version.](./generic.mdx#performance-optimised-builds) |
| Forgejo Registry | [forgejo.ellis.link/continuwuation/continuwuity:main-maxperf](https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main-maxperf)     | [Performance optimised version.](./generic.mdx#performance-optimised-builds) |

**Example:**

```bash
docker image pull forgejo.ellis.link/continuwuation/continuwuity:main-maxperf
```

#### Mirrors

Images are mirrored to multiple locations automatically, on a schedule:

- `ghcr.io/continuwuity/continuwuity`
- `docker.io/jadedblueeyes/continuwuity`
- `registry.gitlab.com/continuwuity/continuwuity`
- `git.nexy7574.co.uk/mirrored/continuwuity` (releases only, no `main`)

### Quick Run

Get a working Continuwuity server with an admin user in four steps:

#### Prerequisites

Continuwuity requires HTTPS for Matrix federation. You'll need:

- A domain name pointing to your server
- A reverse proxy with SSL/TLS certificates (Traefik, Caddy, nginx, etc.)

See [Docker Compose](#docker-compose) for complete examples.

#### Environment Variables

- `CONTINUWUITY_SERVER_NAME` - Your Matrix server's domain name
- `CONTINUWUITY_DATABASE_PATH` - Where to store your database (must match the
  volume mount)
- `CONTINUWUITY_ADDRESS` - Bind address (use `0.0.0.0` to listen on all
  interfaces)
- `CONTINUWUITY_ALLOW_REGISTRATION` - Set to `false` to disable registration, or
  use with `CONTINUWUITY_REGISTRATION_TOKEN` to require a token (see
  [reference](../reference/environment-variables.mdx#registration--user-configuration)
  for details)

See the
[Environment Variables Reference](../reference/environment-variables.mdx) for
more configuration options.

#### 1. Pull the image

```bash
docker pull forgejo.ellis.link/continuwuation/continuwuity:latest
```

#### 2. Start the server with initial admin user

```bash
docker run -d \
  -p 6167:6167 \
  -v continuwuity_db:/var/lib/continuwuity \
  -e CONTINUWUITY_SERVER_NAME="matrix.example.com" \
  -e CONTINUWUITY_DATABASE_PATH="/var/lib/continuwuity" \
  -e CONTINUWUITY_ADDRESS="0.0.0.0" \
  -e CONTINUWUITY_ALLOW_REGISTRATION="false" \
  --name continuwuity \
  forgejo.ellis.link/continuwuation/continuwuity:latest \
  --execute "users create-user admin"
```

Replace `matrix.example.com` with your actual server name and `admin` with
your preferred username.

#### 3. Get your admin password

```bash
docker logs continuwuity 2>&1 | grep "Created user"
```

You'll see output like:

```
Created user with user_id: @admin:matrix.example.com and password: `[auto-generated-password]`
```

#### 4. Configure your reverse proxy

Configure your reverse proxy to forward HTTPS traffic to Continuwuity. See
[Docker Compose](#docker-compose) for examples.

Once configured, log in with any Matrix client using `@admin:matrix.example.com`
and the generated password. You'll automatically be invited to the admin room
where you can manage your server.

### Docker Compose

Docker Compose is the recommended deployment method. These examples include
reverse proxy configurations for Matrix federation.

#### Matrix Federation Requirements

For Matrix federation to work, you need to serve `.well-known/matrix/client` and
`.well-known/matrix/server` endpoints. You can achieve this either by:

1. **Using a well-known service** - The compose files below include an nginx
   container to serve these files
2. **Using Continuwuity's built-in delegation** (easier for Traefik) - Configure
   delegation files in your config, then proxy `/.well-known/matrix/*` to
   Continuwuity

**Traefik example using built-in delegation:**

```yaml
labels:
  traefik.http.routers.continuwuity.rule: >-
    (Host(`matrix.example.com`) ||
     (Host(`example.com`) && PathPrefix(`/.well-known/matrix`)))
```

This routes your Matrix domain and well-known paths to Continuwuity.

#### Creating Your First Admin User

Add the `--execute` command to create an admin user on first startup. In your
compose file, add under the `continuwuity` service:

```yaml
services:
    continuwuity:
        image: forgejo.ellis.link/continuwuation/continuwuity:latest
        command: --execute "users create-user admin"
        # ... rest of configuration
```

Then retrieve the auto-generated password:

```bash
docker compose logs continuwuity | grep "Created user"
```

#### Choose Your Reverse Proxy

Select the compose file that matches your setup:

:::note DNS Performance
Docker's default DNS resolver can cause performance issues with Matrix
federation. If you experience slow federation or DNS timeouts, you may need to
use your host's DNS resolver instead. Add this volume mount to the
`continuwuity` service:

```yaml
volumes:
  - /etc/resolv.conf:/etc/resolv.conf:ro
```

See [Troubleshooting - DNS Issues](../troubleshooting.mdx#potential-dns-issues-when-using-docker)
for more details and alternative solutions.
:::

##### For existing Traefik setup

<details>
<summary>docker-compose.for-traefik.yml</summary>

```yaml file="./docker-compose.for-traefik.yml"

```

</details>

##### With Traefik included

<details>
<summary>docker-compose.with-traefik.yml</summary>

```yaml file="./docker-compose.with-traefik.yml"

```

</details>

##### With Caddy Docker Proxy

<details>
<summary>docker-compose.with-caddy.yml</summary>

Replace all `example.com` placeholders with your own domain.

```yaml file="./docker-compose.with-caddy.yml"

```

If you don't already have a network for Caddy to monitor, create one first:

```bash
docker network create caddy
```

</details>

##### For other reverse proxies

<details>
<summary>docker-compose.yml</summary>

```yaml file="./docker-compose.yml"

```

</details>

##### Override file for customisation

<details>
<summary>docker-compose.override.yml</summary>

```yaml file="./docker-compose.override.yml"

```

</details>

#### Starting Your Server

1. Choose your compose file and rename it to `docker-compose.yml`
2. If using the override file, rename it to `docker-compose.override.yml` and
   edit your values
3. Start the server:

```bash
docker compose up -d
```

See the [generic deployment guide](generic.mdx) for more deployment options.

### Building Custom Images

For information on building your own Continuwuity Docker images, see the
[Building Docker Images](../development/index.mdx#building-docker-images)
section in the development documentation.

## Voice communication

See the [Calls](../calls.mdx) page.