docs(docker): Big refactor with better structuring, simplified examples, and other improvements #1594

stratself · 2026-03-30T09:39:20Z

stratself commented

2026-03-30 09:39:20 +00:00

This pull request essentially refactor the Docker deploying docs and include many new changes. Since this has many huge changes, I believe submitting it early as WIP would help with extensive reviews.

As mentioned in #1508, essentially complete these items:

Rewrite docker ~~and generic~~ instructions to match the new registration flow from #1367
Rearrange docker page to 3 main section: Image, Docker (Quick Start), Docker-Compose. The "Docker - Quick Start" section is shortened.
Use an actual Caddyfile instead of Caddy labels for docker-compose.with-caddy.yml
Make stuff more consistent: use :8008 instead of :6167, use the same env var options for all docker-compose files
Remove crufts (e.g. delegation, Element Web installation) and redirect to proper pages for that if available
Use a custom configs: file for the /etc/resolv.conf mount, with nameserver 1.1.1.1 as content. This would stop people from footgunning themselves with localhost nameservers

It also adds the following niceties:

Add Caddy with Caddyfile example configuration
Move all yml files to docs/public/deploying to allow them to be viewable as raw files on the website.

Todos

Some more changes for coherency will be needed.

This would conflict with @ky-bean's #1553. LIkely, I would copy-and-paste their docs into mine, and mark them as Co-Contributor.

Questions

The big question right now: Should I include .well-known delegation on :443 in the examples, or not? For Caddy it should be simple enough not to do that. But for Traefik (especially when integrating with existing Traefik), it'd simplify the number of ports opened.

Pull request checklist:

This pull request targets the main branch, and the branch is named something other than
main.
I have written an appropriate pull request title and my description is clear.
I understand I am responsible for the contents of this pull request.
I have followed the contributing guidelines:
- My contribution follows the code style, if applicable.
- I ran pre-commit checks before opening/drafting this pull request.
- I have tested my contribution (or proof-read it for documentation-only changes)
  myself, if applicable. This includes ensuring code compiles.
- My commit messages follow the commit message format and are descriptive.
- I have written a news fragment for this PR, if applicable.

This pull request essentially refactor the Docker deploying docs and include many new changes. Since this has many huge changes, I believe submitting it early as WIP would help with extensive reviews. As mentioned in #1508, essentially complete these items: - [x] Rewrite [docker](https://continuwuity.org/deploying/docker) ~~and [generic](https://continuwuity.org/deploying/generic)~~ instructions to match the new registration flow from #1367 - [x] Rearrange [docker](https://continuwuity.org/deploying/docker) page to 3 main section: Image, Docker (Quick Start), Docker-Compose. The "Docker - Quick Start" section is shortened. - [x] Use an actual Caddyfile instead of Caddy labels for `docker-compose.with-caddy.yml` - [x] Make stuff more consistent: use :8008 instead of :6167, use the same env var options for all docker-compose files - [x] Remove crufts (e.g. delegation, Element Web installation) and redirect to proper pages for that if available - [x] Use a custom `configs:` file for the `/etc/resolv.conf` mount, with `nameserver 1.1.1.1` as content. This would stop people from footgunning themselves with localhost nameservers It also adds the following niceties: - [x] Add Caddy with Caddyfile example configuration - [x] Move all yml files to `docs/public/deploying` to allow them to be viewable as raw files on the website. ### Todos Some more changes for coherency will be needed. This would conflict with @ky-bean's #1553. LIkely, I would copy-and-paste their docs into mine, and mark them as Co-Contributor. ### Questions The big question right now: Should I include **`.well-known` delegation** on `:443` in the examples, or not? For Caddy it should be simple enough not to do that. But for Traefik (especially when integrating with existing Traefik), it'd simplify the number of ports opened. --- **Pull request checklist:**  - [x] This pull request targets the `main` branch, and the branch is named something other than `main`. - [x] I have written an appropriate pull request title and my description is clear. - [x] I understand I am responsible for the contents of this pull request. - I have followed the [contributing guidelines][c1]: - [x] My contribution follows the [code style][c2], if applicable. - [x] I ran [pre-commit checks][c1pc] before opening/drafting this pull request. - [x] I have [tested my contribution][c1t] (or proof-read it for documentation-only changes) myself, if applicable. This includes ensuring code compiles. - [x] My commit messages follow the [commit message format][c1cm] and are descriptive. - [x] I have written a [news fragment][n1] for this PR, if applicable. [c1]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md [c2]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/docs/development/code_style.mdx [c1pc]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#pre-commit-checks [c1t]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#running-tests-locally [c1cm]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#commit-messages [n1]: https://towncrier.readthedocs.io/en/stable/tutorial.html#creating-news-fragments

stratself commented

2026-03-30 10:41:22 +00:00

Here's a preview

I had to disable dead link checking to get the yaml URLs to build. It could be nice if this can be toggled only for this page

Here's a [preview](https://muc.muoi.me/deploying/docker.html) I had to [disable dead link checking](https://rspress.rs/guide/use-mdx/link#dead-links-checking) to get the yaml URLs to build. It could be nice if this can be toggled only for this page

stratself force-pushed stratself/docs-docker-improvements from b9ff72e825

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 11s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m53s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 11m19s

Details

to 89e87626cc

Check Changelog / Check for changelog (pull_request_target) Successful in 10s

Details

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m41s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 13m18s

Details

2026-03-30 12:10:29 +00:00

Compare

stratself force-pushed stratself/docs-docker-improvements from 8661fefb08

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 11s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m55s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 11m52s

Details

to c4a409e3b8

Check Changelog / Check for changelog (pull_request_target) Successful in 13s

Details

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m51s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 14m57s

Details

2026-03-31 19:44:47 +00:00

Compare

stratself changed title from ~~WIP: docs(docker): Big refactor with better structuring, simplified examples, and other improvements~~ to docs(docker): Big refactor with better structuring, simplified examples, and other improvements

2026-03-31 20:25:12 +00:00

stratself changed title from ~~docs(docker): Big refactor with better structuring, simplified examples, and other improvements~~ to WIP: docs(docker): Big refactor with better structuring, simplified examples, and other improvements

2026-03-31 20:25:52 +00:00

stratself referenced this pull request

2026-04-01 17:32:08 +00:00

docs: Add DNS tuning guide #1601

stratself force-pushed stratself/docs-docker-improvements from d61ed33f54

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 16s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m58s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled

Details

to b11e267094

Check Changelog / Check for changelog (pull_request_target) Successful in 21s

Details

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m59s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m58s

Details

2026-04-04 07:04:29 +00:00

Compare

stratself referenced this pull request

2026-04-04 18:56:14 +00:00

docs: Add performance tuning guide #1498

stratself force-pushed stratself/docs-docker-improvements from 0ee3675b9c

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 10s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m7s

Details

Update flake hashes / update-flake-hashes (pull_request) Successful in 52s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 15m31s

Details

to 042b4c5d21

Check Changelog / Check for changelog (pull_request_target) Waiting to run

Details

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m16s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 15m20s

Details

2026-04-08 07:46:03 +00:00

Compare

stratself changed title from ~~WIP: docs(docker): Big refactor with better structuring, simplified examples, and other improvements~~ to docs(docker): Big refactor with better structuring, simplified examples, and other improvements

2026-04-08 08:17:58 +00:00

stratself commented

2026-04-08 08:18:44 +00:00

Removing WIP status, as it should be reviewable now. Apologies for the large diffs.

stratself referenced this pull request

2026-04-08 08:25:10 +00:00

docs: Explain how to enable sending admin commands to the server console for docker deployments #1553

stratself requested review from Owners

2026-04-08 11:45:22 +00:00

Jade added the

Documentation

label

2026-04-08 13:54:49 +00:00

Jade reviewed

2026-04-08 14:14:10 +00:00

docs/deploying/docker.mdx Outdated

					
				@ -170,2 +46,3 @@

				for more details and alternative solutions.

				:::tip Split-domain setups

				For more setups with `.well-known` delegation and split-domain deployments, consult the [Delegation/Split-domain](../advanced/delegation) page.

				:::

Might want an additional warning that the server_name cannot be changed

stratself marked this conversation as resolved

Jade reviewed

2026-04-08 14:19:16 +00:00

docs/deploying/docker.mdx Outdated

					
				@ -174,0 +103,4 @@

				- `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).

In docker, CONTINUWUITY_ADDRESS refers to the address bound inside the container. Unlike on a host deployment, you typically want to bind to all interfaces, because requests from other containers (and the host) don't come from localhost, but come from internal IPs. When using docker's port forwarding, docker controls what interfaces are forwarded to the container.

In docker, `CONTINUWUITY_ADDRESS` refers to the address bound inside the container. Unlike on a host deployment, you typically want to bind to all interfaces, because requests from other containers (and the host) don't come from localhost, but come from internal IPs. When using docker's port forwarding, docker controls what interfaces are forwarded to the container.

that is to say, this option won't do what non-docker people expect.

Added pendantic note "(for docker, use 0.0.0.0)"

Added pendantic note "(for docker, use `0.0.0.0`)"

stratself marked this conversation as resolved

Jade approved these changes

2026-04-08 14:21:57 +00:00

stratself force-pushed stratself/docs-docker-improvements from bf01ad01bf

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 8s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled

Details

Update flake hashes / update-flake-hashes (pull_request) Successful in 1m41s

Details

to 807e7d4665

Check Changelog / Check for changelog (pull_request_target) Successful in 8s

Details

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m7s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 10m12s

Details

2026-04-11 15:54:37 +00:00

Compare

stratself commented

2026-04-13 05:15:38 +00:00

Moved "Docker (Quick Test)" and build instructions to an umbrella section called "Other Deployment Options". I think it is better suited there as docker cli alone was never meant for serious prod. Webpage also updated

Moved "Docker (Quick Test)" and build instructions to an umbrella section called "Other Deployment Options". I think it is better suited there as docker cli alone was never meant for serious prod. Webpage also [updated](https://muc.muoi.me/deploying/docker.html#other-deployment-methods)

👍 1

Jade merged commit 955a695138 into main

2026-04-13 17:34:36 +00:00

Jade referenced this pull request from a commit

2026-04-13 17:34:39 +00:00

chore: Add changelog for #1594

stratself referenced this pull request

2026-04-14 16:59:13 +00:00

fix(docs): Remove matrix. subdomains in composes #1660

stratself referenced this pull request

2026-04-15 14:40:13 +00:00

docs: Add delegation compose files and fix old ones #1670