continuwuation/continuwuity
continuwuation/continuwuity
14
83
Fork 95
Code Issues 131 Pull requests 33 Releases 27 Packages 3 Activity Actions 19

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

Draft
stratself wants to merge 14 commits from stratself/continuwuity:stratself/docs-docker-improvements into main
pull from: stratself/continuwuity:stratself/docs-docker-improvements
merge into: continuwuation:main
Conversation 1 Commits 14 Files changed 12 +363 -467
stratself commented 2026-03-30 09:39:20 +00:00
Contributor
Copy link

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:
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:** <!-- You need to complete these before your PR can be considered. If you aren't sure about some, feel free to ask for clarification in #dev:continuwuity.org. --> - [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. - [ ] I have written a [news fragment][n1] for this PR, if applicable<!--(can be done after hitting open!)-->. [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 
* docs: Make "Available Images" a top-level option, to be followed by
  Docker and Docker Compose sections in a future commit
* docs: Make "Mirrors" a subsection of "Available images", and add
  links to the mirrors themselves
* docs: Use indirect linkages to URLs for better maintainability
* docs: Remove initial sentence and its reference to the (advanced)
  building your image flow
* docs: Recommend `latest` OCI tag and include link to
* docs: "Docker - Quick Run" and "Docker Compose" are now two top-level
  sections
* docs: Mark building your images as "(Optional)"
* docs: Move calls to "Next step" section
* docs: Remove Matrix Federation Requirements for simpler deployments
* docs: Remove redundant env vars in Docker - Quick Run
* Remove unnecessary c10y env vars
* Remove unnecessary comment about image build and vim
* Remove references to Element-Web

Other changes like unified port and domain names will be in a future
commit
Included some additional comments. .well-known Delegation seems to be
much more convenient for traefik + caddy. How they're documented can be
decided in a future commit.
* Add compose and included Caddyfile using caddy:latest official image
* Rename old Caddy files as caddy-labels.yml and new one as caddy.yml
* Remove external: true network in caddy-labels.yml to simplify docs
* Move all Caddy selections to top, unprioritize Traefik and other RPs
The file defines an HSTS middleware and cipher suite prefs, which
should not be needed for a simple deployment
* 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
* Also add a note disclaiming that Docker is for demo purposes only
* Use port 8008 for Docker Quick Run instructions
* Remove the steps to create first admin user

I do believe "Docker - Quick Run" should be moved to after Docker
Compose section, but will want to discuss this before advancing
docs(docker): Rewrite Docker DNS workaround with custom resolv.conf
Some checks failed
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
b9ff72e825 
Instead of /etc/resolv.conf on host. This works around the
systemd-resolved footgunning issue and provide an inline way to
configure resolvers, separate from that of the host system.
stratself commented 2026-03-30 10:41:22 +00:00
Author
Contributor
Copy link

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
Some checks failed
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
Some checks failed
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
chore: Add changelog for #1594
Some checks failed
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
8661fefb08
stratself force-pushed stratself/docs-docker-improvements from 8661fefb08
Some checks failed
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
Some checks failed
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
fix(docs): exclude local .yml URLs from dead link checking
Some checks failed
Check Changelog / Check for changelog (pull_request_target) Successful in 11s
Details
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Details
Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m52s
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 13m51s
Details
cecf96df1d
docs(docker): Update links for DNS tuning guide
Some checks failed
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) Failing after 3m4s
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m51s
Details
6fdcf8001a
docs(docker): Mount /etc/resolv.conf as config files don't work
Some checks failed
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 / Clippy and Cargo Tests (pull_request) Has been cancelled
Details
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Details
f1e1033295 
Also use more imperative wording for the DNS tuning recommendation
docs(docker): Remove ulimits and cpuset instructions for simplicity
Some checks failed
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
d61ed33f54 
Increasing nofiles can be done in perf-tuning (#1498) instead
stratself force-pushed stratself/docs-docker-improvements from d61ed33f54
Some checks failed
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
All checks were successful
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
All checks were successful
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
Required
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m58s
Required
Details
This pull request is marked as a work in progress.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u stratself/docs-docker-improvements:stratself-stratself/docs-docker-improvements
git switch stratself-stratself/docs-docker-improvements
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
Blocked

This pull request or issue is currently blocked from being merged/closed

  
Bug

Something isn't working as intended

  
Cherry-picking

Commits picked from other conduit projects

  
Database

This requires or includes changes to the database

  
Dependencies

Something dependency related

  
Dependencies/Renovate

Automatic dependency upgrades by Renovate

  
Difficulty
Easy
Low difficulty to implement - touches few parts of the codebase, low complexity

  
Difficulty
Hard
High difficulty to implement - touches many parts of the codebase, high complexity

  
Difficulty
Medium
Medium difficulty to implement - touches more parts of the codebase, higher complexity

  
Documentation

Improvements or additions to documentation

  
Enhancement

New feature or request

  
Good first issue

Good for newcomers

  
Help wanted

Additional eyes and keyboards are required for this one

  
Inherited

Issues that have been inhereted from the project pre-fork

  
Input Acknowledged

   
Matrix/Administration

Features pertaining to homeserver administration

  
Matrix/Appservices

Features pertaining to the appservice API

  
Matrix/Auth

Features pertaining to authentication

  
Matrix/Client

Features pertaining to client-to-server interactions

  
Matrix/Core

Issues relating to core matrix functionality, such as state resolution and PDU formats

  
Matrix/E2EE

Issues related to end to end encryption

  
Matrix/Federation

Features pertaining to server-to-server interactions

  
Matrix/Hydra

Issues related to room version 12 and related changes (temporary label)

  
Matrix/MSC

Features pertaining to unstable matrix features

  
Matrix/Media

Features pertaining to media interactions

  
Matrix/T&S

Changes or issues related to trust & safety tooling

  
Meta

Related to housekeeping, maintenance, or other repo-meta.

  
Meta/CI

Issues related to CI changes

  
Meta/Packaging

Packaging

  
Priority
Blocking
This issue is blocking the next release

  
Priority
High
This issue is very important

  
Priority
Low
This issue is of a rather low priority

  
Security

This item is related to general security

  
Status
Confirmed
This issue has enough information and is confirmed

  
Status
Duplicate
This issue or pull request already exists

  
Status
Invalid
This issue doesn't seem right

  
Status
Needs Investigation
This issue needs further investigation

  
Support

Questions or support requests

  
To-Merge

   
Wont fix

This will not be worked on

  
old/ci/cd

Ci/CD

Archived

  
old/rust

Pull requests that update Rust code

Archived

No labels
Blocked
Bug
Cherry-picking
Database
Dependencies
Dependencies/Renovate
Difficulty
Easy
Difficulty
Hard
Difficulty
Medium
Documentation
Enhancement
Good first issue
Help wanted
Inherited
Input Acknowledged
Matrix/Administration
Matrix/Appservices
Matrix/Auth
Matrix/Client
Matrix/Core
Matrix/E2EE
Matrix/Federation
Matrix/Hydra
Matrix/MSC
Matrix/Media
Matrix/T&S
Meta
Meta/CI
Meta/Packaging
Priority
Blocking
Priority
High
Priority
Low
Security
Status
Confirmed
Status
Duplicate
Status
Invalid
Status
Needs Investigation
Support
To-Merge
Wont fix
old/ci/cd
old/rust
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
continuwuation/continuwuity!1594
No description provided.