Mirrors/continuwuity
1
0
Fork 0
mirror of https://forgejo.ellis.link/continuwuation/continuwuity.git synced 2026-05-26 20:49:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(docker): Make example ymls raw-viewable and other copyedit fixes

Browse Source 
* Move all *.yml files to docs/public/deploying so they can be viewable
  as raw files on the webpage
* Link to those files with "(view raw)"
* Move minimal environment variables to Docker Compose section
* Unheading the Docker Quick Run stuff to prepare deprioritizing them
* Remove redundant Registry column in Image table
* Rename reverse proxy subsections to have software name as first word
This commit is contained in:
stratself
2026-03-29 09:48:10 +00:00
committed by Ellis Git
parent a575e21598
commit 6a8850b556
7 changed files with 71 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deploying/docker-compose.for-traefik.yml
-50
View File
@@ -1,50 +0,0 @@
# Continuwuity - Behind Traefik Reverse Proxy
services:
homeserver:
image: forgejo.ellis.link/continuwuation/continuwuity:latest
restart: unless-stopped
command: /sbin/conduwuit
volumes:
- db:/var/lib/continuwuity
#- ./continuwuity.toml:/etc/continuwuity.toml
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.continuwuity.rule=(Host(`matrix.example.com`) || (Host(`example.com`) && PathPrefix(`/.well-known/matrix`)))"
- "traefik.http.routers.continuwuity.entrypoints=websecure" # your HTTPS entry point
- "traefik.http.routers.continuwuity.tls=true"
- "traefik.http.routers.continuwuity.service=continuwuity"
- "traefik.http.services.continuwuity.loadbalancer.server.port=8008"
# possibly, depending on your config:
# - "traefik.http.routers.continuwuity.tls.certresolver=letsencrypt"
environment:
CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS
CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity
CONTINUWUITY_ADDRESS: 0.0.0.0
CONTINUWUITY_PORT: 8008 # This must match with traefik's loadbalancer label
#CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above
# We need some way to serve the client and server .well-known json. The simplest way is via the CONTINUWUITY_WELL_KNOWN
# variable / config option, there are multiple ways to do this, e.g. in the continuwuity.toml file, and in a separate
# see the override file for more information about delegation
CONTINUWUITY_WELL_KNOWN: |
{
client=https://matrix.example.com,
server=matrix.example.com:443
}
#cpuset: "0-4" # Uncomment to limit to specific CPU cores
ulimits: # Continuwuity uses quite a few file descriptors, and on some systems it defaults to 1024, so you can tell docker to increase it
nofile:
soft: 1048567
hard: 1048567
volumes:
db:
networks:
# This is the network Traefik listens to, if your network has a different
# name, don't forget to change it here and in the docker-compose.override.yml
proxy:
external: true
docs/deploying/docker-compose.override.yml
-26
View File
@@ -1,26 +0,0 @@
# Continuwuity - Traefik Reverse Proxy Labels
services:
homeserver:
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy" # Change this to the name of your Traefik docker proxy network
- "traefik.http.routers.to-continuwuity.rule=Host(`matrix.example.com`)" # Change to the address on which Continuwuity is hosted
- "traefik.http.routers.to-continuwuity.tls=true"
- "traefik.http.routers.to-continuwuity.tls.certresolver=letsencrypt"
- "traefik.http.routers.to-continuwuity.middlewares=cors-headers@docker"
# This must match with CONTINUWUITY_PORT (default: 8008)
- "traefik.http.services.to_continuwuity.loadbalancer.server.port=8008"
- "traefik.http.middlewares.cors-headers.headers.accessControlAllowOriginList=*"
- "traefik.http.middlewares.cors-headers.headers.accessControlAllowHeaders=Origin, X-Requested-With, Content-Type, Accept, Authorization"
- "traefik.http.middlewares.cors-headers.headers.accessControlAllowMethods=GET, POST, PUT, DELETE, OPTIONS"
# If you want to have your account on <DOMAIN>, but host Continuwuity on a subdomain,
# you can let it only handle the well known file on that domain instead
#- "traefik.http.routers.to-matrix-wellknown.rule=Host(`example.com`) && PathPrefix(`/.well-known/matrix`)"
#- "traefik.http.routers.to-matrix-wellknown.tls=true"
#- "traefik.http.routers.to-matrix-wellknown.tls.certresolver=letsencrypt"
#- "traefik.http.routers.to-matrix-wellknown.middlewares=cors-headers@docker"
docs/deploying/docker-compose.with-caddy-labels.yml
-49
View File
@@ -1,49 +0,0 @@
services:
caddy:
# This compose file uses caddy-docker-proxy as the reverse proxy for Continuwuity!
# For more info, visit https://github.com/lucaslorentz/caddy-docker-proxy
image: lucaslorentz/caddy-docker-proxy:ci-alpine
ports:
- 80:80
- 443:443
environment:
- CADDY_INGRESS_NETWORKS=caddy
networks:
- caddy
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./data:/data
restart: unless-stopped
labels:
caddy: example.com
caddy.reverse_proxy: /.well-known/matrix/* homeserver:8008
homeserver:
image: forgejo.ellis.link/continuwuation/continuwuity:latest
restart: unless-stopped
command: /sbin/conduwuit
volumes:
- db:/var/lib/continuwuity
- /etc/resolv.conf:/etc/resolv.conf:ro # Use the host's DNS resolver rather than Docker's.
#- ./continuwuity.toml:/etc/continuwuity.toml
environment:
CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS
CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity
CONTINUWUITY_ADDRESS: 0.0.0.0
CONTINUWUITY_PORT: 8008
#CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above
# Required for .well-known delegation - edit these according to your chosen domain
CONTINUWUITY_WELL_KNOWN__CLIENT: https://matrix.example.com
CONTINUWUITY_WELL_KNOWN__SERVER: matrix.example.com:443
networks:
- caddy
labels:
caddy: matrix.example.com
caddy.reverse_proxy: "{{upstreams 8008}}"
volumes:
db:
networks:
caddy:
docs/deploying/docker-compose.with-caddy.yml
-45
View File
@@ -1,45 +0,0 @@
networks:
caddy:
volumes:
db:
configs:
dynamic.yml:
content: |
https://example.com, https://example.com:8448 {
reverse_proxy http://homeserver:8008
}
services:
caddy:
image: docker.io/caddy:latest
ports:
- 80:80
- 443:443
- 8448:8448
networks:
- caddy
volumes:
- ./data:/data
restart: unless-stopped
configs:
- source: Caddyfile
target: /etc/caddy/Caddyfile
homeserver:
image: forgejo.ellis.link/continuwuation/continuwuity:latest
restart: unless-stopped
command: /sbin/conduwuit
volumes:
- db:/var/lib/continuwuity
- /etc/resolv.conf:/etc/resolv.conf:ro # Use the host's DNS resolver rather than Docker's.
#- ./continuwuity.toml:/etc/continuwuity.toml
environment:
CONTINUWUITY_SERVER_NAME: example.com
CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity
CONTINUWUITY_ADDRESS: 0.0.0.0
CONTINUWUITY_PORT: 8008
#CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above
networks:
- caddy
docs/deploying/docker-compose.with-traefik.yml
-92
View File
@@ -1,92 +0,0 @@
# Continuwuity - Behind Traefik Reverse Proxy
services:
homeserver:
image: forgejo.ellis.link/continuwuation/continuwuity:latest
restart: unless-stopped
command: /sbin/conduwuit
volumes:
- db:/var/lib/continuwuity
- /etc/resolv.conf:/etc/resolv.conf:ro # Use the host's DNS resolver rather than Docker's.
#- ./continuwuity.toml:/etc/continuwuity.toml
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.continuwuity.rule=(Host(`matrix.example.com`) || (Host(`example.com`) && PathPrefix(`/.well-known/matrix`)))"
- "traefik.http.routers.continuwuity.entrypoints=websecure"
- "traefik.http.routers.continuwuity.tls.certresolver=letsencrypt"
- "traefik.http.services.continuwuity.loadbalancer.server.port=8008"
environment:
CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS
CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity
CONTINUWUITY_ADDRESS: 0.0.0.0
CONTINUWUITY_PORT: 8008 # This must match with traefik's loadbalancer label
#CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above
# We need some way to serve the client and server .well-known json. The simplest way is via the CONTINUWUITY_WELL_KNOWN
# variable / config option, there are multiple ways to do this, e.g. in the continuwuity.toml file, and in a separate
# reverse proxy, but since you do not have a reverse proxy and following this guide, this example is included
CONTINUWUITY_WELL_KNOWN: |
{
client=https://matrix.example.com,
server=matrix.example.com:443
}
#cpuset: "0-4" # Uncomment to limit to specific CPU cores
ulimits: # Continuwuity uses quite a few file descriptors, and on some systems it defaults to 1024, so you can tell docker to increase it
nofile:
soft: 1048567
hard: 1048567
traefik:
image: "traefik:latest"
container_name: "traefik"
restart: "unless-stopped"
ports:
- "80:80"
- "443:443"
volumes:
- "/var/run/docker.sock:/var/run/docker.sock:z"
- "acme:/etc/traefik/acme"
#- "./traefik_config:/etc/traefik:z"
labels:
- "traefik.enable=true"
# middleware redirect
- "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"
# global redirect to https
- "traefik.http.routers.redirs.rule=hostregexp(`{host:.+}`)"
- "traefik.http.routers.redirs.entrypoints=web"
- "traefik.http.routers.redirs.middlewares=redirect-to-https"
environment:
TRAEFIK_LOG_LEVEL: DEBUG
TRAEFIK_ENTRYPOINTS_WEB: true
TRAEFIK_ENTRYPOINTS_WEB_ADDRESS: ":80"
TRAEFIK_ENTRYPOINTS_WEB_HTTP_REDIRECTIONS_ENTRYPOINT_TO: websecure
TRAEFIK_ENTRYPOINTS_WEBSECURE: true
TRAEFIK_ENTRYPOINTS_WEBSECURE_ADDRESS: ":443"
TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_TLS_CERTRESOLVER: letsencrypt
TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT: true
# CHANGE THIS to desired email for ACME
TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_EMAIL: user@example.com
TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE: true
TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_HTTPCHALLENGE_ENTRYPOINT: web
TRAEFIK_CERTIFICATESRESOLVERS_LETSENCRYPT_ACME_STORAGE: "/etc/traefik/acme/acme.json"
# Since Traefik 3.6.3, paths with certain "encoded characters" are now blocked by default; we need a couple, or else things *will* break
TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDSLASH: true
TRAEFIK_ENTRYPOINTS_WEBSECURE_HTTP_ENCODEDCHARACTERS_ALLOWENCODEDHASH: true
TRAEFIK_PROVIDERS_DOCKER: true
TRAEFIK_PROVIDERS_DOCKER_ENDPOINT: "unix:///var/run/docker.sock"
TRAEFIK_PROVIDERS_DOCKER_EXPOSEDBYDEFAULT: false
volumes:
db:
acme:
networks:
proxy:
docs/deploying/docker-compose.yml
-21
View File
@@ -1,21 +0,0 @@
# Continuwuity
services:
homeserver:
image: forgejo.ellis.link/continuwuation/continuwuity:latest
restart: unless-stopped
command: /sbin/conduwuit
ports:
- 127.0.0.1:8008:8008
volumes:
- db:/var/lib/continuwuity
#- ./continuwuity.toml:/etc/continuwuity.toml
environment:
CONTINUWUITY_SERVER_NAME: example.com # EDIT THIS
CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity
CONTINUWUITY_ADDRESS: 0.0.0.0
CONTINUWUITY_PORT: 8008
#CONTINUWUITY_CONFIG: '/etc/continuwuity.toml' # Uncomment if you mapped config toml above
volumes:
db:
docs/deploying/docker.mdx
+71 -78
View File
@@ -6,12 +6,12 @@
The following OCI images are available for Continuwuity:
| Registry | Image | Notes |
| ---------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Forgejo Registry | [https://forgejo.ellis.link/continuwuation/continuwuity:**latest**][latest] | Latest tagged release. (recommended) |
| Forgejo Registry | [https://forgejo.ellis.link/continuwuation/continuwuity:**main**][main] | Latest `main` branch commit. |
| Forgejo Registry | [https://forgejo.ellis.link/continuwuation/continuwuity:**latest-maxperf**][latest-maxperf] | Latest tagged release, [performance optimised version](./generic.mdx#performance-optimised-builds). |
| Forgejo Registry | [https://forgejo.ellis.link/continuwuation/continuwuity:**main-maxperf**][main-maxperf] | Latest `main` branch commit, [performance optimised version](./generic.mdx#performance-optimised-builds). |
| 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
@@ -39,64 +39,52 @@ 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` and `:8448` opened on your server's firewall.
- Port `:443` (for Client-Server traffic) and `:8448` (for federation traffic) opened on your server's firewall.
:::tip Alternative setups
For other deployment options such as serving `.well-known` files, consult the [Delegation/Split-domain](../advanced/delegation) page.
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:
### Environment Variables
1. Pull the image
- `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)
```bash
docker pull forgejo.ellis.link/continuwuation/continuwuity:latest
```
For a list of all config options, see the [reference configuration](../reference/config) page
2. Start the server with initial admin user
### 1. Pull the image
```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"
```
```bash
docker pull forgejo.ellis.link/continuwuation/continuwuity:latest
```
Replace `matrix.example.com` with your actual server name and `admin` with your preferred username.
### 2. Start the server with initial admin user
3. Get your admin password
```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"
```
```bash
docker logs continuwuity 2>&1 | grep "Created user"
```
Replace `matrix.example.com` with your actual server name and `admin` with
your preferred username.
You'll see output like:
### 3. Get your admin password
```
Created user with user_id: @admin:matrix.example.com and password: `[auto-generated-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.
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
@@ -104,10 +92,15 @@ where you can manage your server.
## Docker Compose
Docker Compose is the recommended deployment method. These examples include
reverse proxy configurations for Matrix federation.
Docker Compose is the recommended deployment method for Continuwuity containers. The following environment variables will be set:
This routes your Matrix domain and well-known paths to Continuwuity.
- `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
@@ -130,7 +123,7 @@ docker compose logs continuwuity | grep "Created user"
### Choose Your Reverse Proxy
Select the compose file that matches your setup:
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
@@ -147,45 +140,56 @@ See [Troubleshooting - DNS Issues](../troubleshooting.mdx#potential-dns-issues-w
for more details and alternative solutions.
:::
#### With Caddy (using Caddyfile)
#### Caddy (using Caddyfile)
<details>
<summary>docker-compose.with-caddy.yml</summary>
<summary>docker-compose.with-caddy.yml ([view raw](./docker-compose.with-caddy.yml))</summary>
```yaml file="./docker-compose.with-caddy.yml"
```yaml file="../public/deploying/docker-compose.with-caddy.yml"
```
</details>
#### With Caddy (using labels)
#### Caddy (using labels)
<details>
<summary>docker-compose.with-caddy-labels.yml</summary>
<summary>docker-compose.with-caddy-labels.yml ([view raw](./docker-compose.with-caddy-labels.yml))</summary>
```yaml file="./docker-compose.with-caddy-labels.yml"
```yaml file="../public/deploying/docker-compose.with-caddy-labels.yml"
```
</details>
#### For existing Traefik setup
#### Traefik (for existing setup)
<details>
<summary>docker-compose.for-traefik.yml</summary>
<summary>docker-compose.for-traefik.yml ([view raw](./docker-compose.for-traefik.yml))</summary>
```yaml file="./docker-compose.for-traefik.yml"
```yaml file="../public/deploying/docker-compose.for-traefik.yml"
```
</details>
#### With Traefik included
#### Traefik included
<details>
<summary>docker-compose.with-traefik.yml</summary>
<summary>docker-compose.with-traefik.yml ([view raw](./docker-compose.with-traefik.yml))</summary>
```yaml file="./docker-compose.with-traefik.yml"
```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"
```
@@ -194,27 +198,16 @@ for more details and alternative solutions.
#### For other reverse proxies
<details>
<summary>docker-compose.yml</summary>
<summary>docker-compose.yml ([view raw](./docker-compose.yml))</summary>
```yaml file="./docker-compose.yml"
```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`
</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`