continuwuity/docs/deploying/docker.mdx

# Continuwuity for Docker

## Preparation

### Choose an image

The following OCI images are available for Continuwuity:

| Image                                                                                        | Notes                                                                                                     |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [https://forgejo.ellis.link/continuwuation/continuwuity:**latest**][latest]                 | Latest tagged release. (recommended)                                                                      |
| [https://forgejo.ellis.link/continuwuation/continuwuity:**main**][main]                     | Latest `main` branch commit.                                                                              |
| [https://forgejo.ellis.link/continuwuation/continuwuity:**latest-maxperf**][latest-maxperf] | Latest tagged release, [performance optimised version](./generic.mdx#performance-optimised-builds).       |
| [https://forgejo.ellis.link/continuwuation/continuwuity:**main-maxperf**][main-maxperf]     | Latest `main` branch commit, [performance optimised version](./generic.mdx#performance-optimised-builds). |

[latest]: https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest
[main]: https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main
[latest-maxperf]: https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/latest-maxperf
[main-maxperf]: https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/main-maxperf

If you want a specific version or commit hash, you can browse for them [here][oci-all-versions].

Images are also mirrored to these locations automatically, on a schedule:

- `ghcr.io/continuwuity/continuwuity` ([Github Registry][ghcr-io])
- `docker.io/jadedblueeyes/continuwuity` ([Docker Hub][docker-hub])
- `registry.gitlab.com/continuwuity/continuwuity` ([Gitlab Registry][gitlab-registry])
- `git.nexy7574.co.uk/mirrored/continuwuity` ([Nexy's forge][nexy-forge]. Releases only, no `main` tags)

[oci-all-versions]: https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/versions
[ghcr-io]: https://github.com/continuwuity/continuwuity/pkgs/container/continuwuity/versions?filters%5Bversion_type%5D=tagged
[docker-hub]: https://hub.docker.com/r/jadedblueeyes/continuwuity/
[gitlab-registry]: https://gitlab.com/continuwuity/continuwuity/container_registry/8871720
[nexy-forge]: https://git.nexy7574.co.uk/mirrored/-/packages/container/continuwuity/versions

### Prerequisites

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

- A domain name pointing to your server's IP address - we will be using `example.com` in this guide.
- A reverse proxy with SSL/TLS certificates (Traefik, Caddy, nginx, etc.) - see [Docker Compose](#docker-compose) for complete examples.
- Port `:443` (for Client-Server traffic) and `:8448` (for federation traffic) opened on your server's firewall.

:::tip Alternative setups
For setups with `.well-known` delegation, different ports, and/or split-domain deployments, consult the [Delegation/Split-domain](../advanced/delegation) page.
:::

## Docker - Quick Run

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

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 \
      /sbin/conduwuit --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 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 for Continuwuity containers. The following environment variables will be set:

- `CONTINUWUITY_SERVER_NAME` - Your Matrix server's domain name.
- `CONTINUWUITY_DATABASE_PATH` - Where to store your database. This must match the docker volume mount.
- `CONTINUWUITY_ADDRESS` - Bind address (use `0.0.0.0` to listen on all interfaces).

Alternatively, you can specify a path to mount the configuration file using the `CONTINUWUITY_CONFIG` environment variable.

See the [reference configuration](../reference/config) page for all config options, and the [Configuration page](../configuration#environment-variables) on how to convert them into Environment Variables.

### 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: /sbin/conduwuit --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

These examples include reverse proxy configurations for Matrix federation, which will route your Matrix domain (and optionally .well-known paths) to Continuwuity.

:::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.
:::

#### Caddy (using Caddyfile)

<details>
<summary>docker-compose.with-caddy.yml ([view raw](./docker-compose.with-caddy.yml))</summary>

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

```

</details>

#### Caddy (using labels)

<details>
<summary>docker-compose.with-caddy-labels.yml ([view raw](./docker-compose.with-caddy-labels.yml))</summary>

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

```

</details>

#### Traefik (for existing setup)

<details>
<summary>docker-compose.for-traefik.yml ([view raw](./docker-compose.for-traefik.yml))</summary>

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

```

</details>

#### Traefik included

<details>
<summary>docker-compose.with-traefik.yml ([view raw](./docker-compose.with-traefik.yml))</summary>

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

```

</details>

#### Traefik (as override file)

<details>
<summary>docker-compose.override.yml ([view raw](./docker-compose.override.yml))</summary>

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

```

</details>

#### For other reverse proxies

<details>
<summary>docker-compose.yml ([view raw](./docker-compose.yml))</summary>

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

```

</details>

You will then need to point your reverse proxy towards Continuwuity at `127.0.0.1:8008`

### 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.

## (Optional) 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.

## Next steps

- To set up Audio/Video communication, see the [Calls](../calls.mdx) page.