Tom Foster
5a44f3e5e4
Add Quick Run section with complete getting-started workflow including admin user creation via --execute flag. Consolidate Docker Compose to treat reverse proxy as essential with Traefik/Caddy/nginx examples. Move detailed image building to development guide, keeping deployment docs focused on using pre-built images. Create environment variables reference with practical examples and context. Clarify built-in TLS is for testing only; production should use reverse proxies.
257 lines
7.7 KiB
Text
257 lines
7.7 KiB
Text
# 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.
|