docs(docker): Restructure deployment guide and add env var reference #1361
Open
tcpipuk
wants to merge 1 commit from
tcpipuk/docker-docs into main
pull from: tcpipuk/docker-docs
merge into: continuwuation:main
continuwuation:main
continuwuation:nex/fix/informative-startup-errs
continuwuation:renovate/tokio-1.x-lockfile
continuwuation:aranje/illegal-car-mods
continuwuation:ginger/password-reset
continuwuation:ginger/no-left-room-initial-sync
continuwuation:nex/feat/policy-servers-2-electric-boogaloo
continuwuation:renovate/rust-patch-updates
continuwuation:jade/docker-entrypoint
continuwuation:jade/dehydrated-devices
continuwuation:ginger/complement-fixes
continuwuation:nex/fix/stale-destination-cache
continuwuation:nex/experiment/sync-mutex
continuwuation:jade/snafu
continuwuation:renovate/serde_html_form-0.x
continuwuation:jade/rand-update
continuwuation:renovate/reqwest-0.x
continuwuation:nex/stateres-refactor
continuwuation:ginger/779-in-troubleshooting
continuwuation:jade/liveit-guide
continuwuation:jade/http3
continuwuation:nex/feat/admin-hide-empty-rooms
continuwuation:ginger/oobe
continuwuation:nex/fix/debian-thingy
continuwuation:jade/ldap-admin-check
continuwuation:nex/fix/remote-restricted-joins
continuwuation:nex/feat/msc4406-sender-ignored
continuwuation:jade/deadlock-detection
continuwuation:nex/feat/room-shutdown
continuwuation:jade/get-started
continuwuation:jade/docs-guide
continuwuation:ginger/fix-local-invites
continuwuation:nex/fix/tpi
continuwuation:nex/feat/room-deletion
continuwuation:nex/feat/msc4322-media-redaction
continuwuation:ginger/stitched-order
continuwuation:jade/build-info
continuwuation:ginger/deps/update-rspress
continuwuation:jade/admin-announce-improvements
continuwuation:ginger/xtask-improvements
continuwuation:jade/improve-admin-config-display
continuwuation:nex/fix/better-stateres-error-logs
continuwuation:jade/sender-timeouts
continuwuation:nex/feat/custom-v12-room-ids
continuwuation:ginger/update-metadata
continuwuation:nex/feat/admin-force-logout
continuwuation:tom/max-perf-docs
continuwuation:nex/fix/invalid-appservice-reg
continuwuation:nex/feat/antispam
continuwuation:nex/feat/account-locking
continuwuation:jade/logging-cleanup
continuwuation:jade/remove-legacy-appservice-auth
continuwuation:nex/fix/key-query
continuwuation:jade/update-prek
continuwuation:nex/fix/room-summaries
continuwuation:ginger/restrict-admin-commands
continuwuation:ginger/enable-console-by-default
continuwuation:jade/tag-fixes
continuwuation:jade/otlp
continuwuation:nex/meta/pull-req-template
continuwuation:nex/fix/fed-invite-compliance
continuwuation:nex/feat/build-commit
continuwuation:nex/feat/join-logging
continuwuation:jade/mailmap-updates
continuwuation:jade/hack-ci-tmp
continuwuation:jade/v12-stable
continuwuation:jade/relations
continuwuation:ginger/database-refactor
continuwuation:jade/fix-ldap-uiaa
continuwuation:nex/fix/validation
continuwuation:ginger/nuke-invalid-msc4133-fields-in-migration
continuwuation:ginger/downgrade-artifact-actions
continuwuation:oddlid/reload-fix
continuwuation:jade/fix-assert
continuwuation:ginger/sync-v3-cleanup
continuwuation:ginger/remove-absolute-action-urls
continuwuation:jade/website
continuwuation:nex/fix/backoff
continuwuation:ginger/fix-mdbook-for-0.5
continuwuation:ginger/no-docker-on-prs
continuwuation:backport/v0.5.0-rc.8-1
continuwuation:nex/fed-improvements
continuwuation:jade/rust-1.90
continuwuation:jade/mirror-dockerhub
continuwuation:jade/clippy-fixes
continuwuation:jade/fix-support
continuwuation:jade/clean-images
continuwuation:jade/wal-compression-type
continuwuation:jade/flake-clone
continuwuation:ginger/upload-rpms-on-schedule
continuwuation:nex/fix/incoming-fetch
continuwuation:nex/fix/upgrade
continuwuation:tom/ci-fedora-rpm
continuwuation:jade/ci-release-fix
continuwuation:jade/rocksdb-10-5
continuwuation:ginger/fix-msc4133-migration
continuwuation:ginger/migrate-busted-tz
continuwuation:hydra/public
continuwuation:nex/feat/manual-extremities
continuwuation:nex/feat/async-media
continuwuation:nex/feat/fast-joins-hack-do-not-use-DO-NOT-USE
continuwuation:nex/feat/better-logging
continuwuation:trigger-ci-so-latest-isnt-on-illegal-car-mods
continuwuation:nex/feat/pins-backfill
continuwuation:jade/tuwunel-2025-06-old
continuwuation:jade/ai-slop-db-docs
continuwuation:nex/fix-create-auth
continuwuation:jade/version-stats
continuwuation:jade/read-receipts
continuwuation:jade/rust-toolchain-no-targets
continuwuation:jade/logging-features
continuwuation:jade/syncv5-typing
continuwuation:jade/msc2815
continuwuation:jade/purge-sync-tokens
continuwuation:morguldir/see-eye
continuwuation:jade/css-small-screen
continuwuation:nex/wip-751
continuwuation:tuwunel-rebase
continuwuation:test
continuwuation:oddlid/rename-admin-room-bot
continuwuation:strawberry/nix-ci-stuff
continuwuation:strawberry/valgrind
continuwuation:phonemain
continuwuation:strawberry/morgs-snake-sync-jason-main
continuwuation:newer-media-endpoints
continuwuation:folly-coroutines-async-io
continuwuation:federation-retry-timer-port
continuwuation:bad-attempt-at-extracting-homeserver-signing-key
continuwuation:room-deletion-attempt-do-not-use
Labels
Clear labels
This pull request or issue is currently blocked from being merged/closed
Something isn't working as intended
Commits picked from other conduit projects
This requires or includes changes to the database
Something dependency related
Automatic dependency upgrades by Renovate
Low difficulty to implement - touches few parts of the codebase, low complexity
High difficulty to implement - touches many parts of the codebase, high complexity
Medium difficulty to implement - touches more parts of the codebase, higher complexity
Improvements or additions to documentation
New feature or request
Good for newcomers
Additional eyes and keyboards are required for this one
Issues that have been inhereted from the project pre-fork
Features pertaining to homeserver administration
Features pertaining to the appservice API
Features pertaining to authentication
Features pertaining to client-to-server interactions
Issues relating to core matrix functionality, such as state resolution and PDU formats
Features pertaining to server-to-server interactions
Issues related to room version 12 and related changes (temporary label)
Features pertaining to unstable matrix features
Features pertaining to media interactions
Changes or issues related to trust & safety tooling
Related to housekeeping, maintenance, or other repo-meta.
Issues related to CI changes
Packaging
This issue is blocking the next release
This issue is very important
This issue is of a rather low priority
This item is related to general security
This issue has enough information and is confirmed
This issue or pull request already exists
This issue doesn't seem right
This issue needs further investigation
Questions or support requests
This will not be worked on
Ci/CD
Pull requests that update Rust code
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
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
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
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
5 participants
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!1361
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "tcpipuk/docker-docs"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
To fix #1360, 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.
Preview:
@ -57,3 +69,1 @@If you just want to test Continuwuity for a short time, you can use the `--rm`flag, which cleans up everything related to your container after you stopit.Replace `matrix.example.com` with your actual server name.and admin with your preferred username
@ -60,0 +97,4 @@volume mount)- `CONTINUWUITY_ADDRESS` - Bind address (use `0.0.0.0` to listen on allinterfaces)- `CONTINUWUITY_ALLOW_REGISTRATION` - Set to `false` to prevent openuh to prevent any registration
I've clarified this, and added a note about reg tokens
@ -64,1 +109,3 @@of the provided `docker-compose` files.Docker Compose is the recommended deployment method for Continuwuity with areverse proxy. These examples include both Continuwuity and a reverse proxyconfigured for Matrix federation.style: I feel like some of these paragraphs could be more consise in the context of the guide? feels a bit repetitive to be saying "Continuwuity and a reverse proxy" again
I've tightened up a few bits including this!
@ -69,0 +115,4 @@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** (recommended for Traefik) - The compose filesa rule like
traefik.http.routers.conduwuit-testing.rule=(Host(matrix.pissing.dev) || (Host(pissing.dev) && PathPrefix(/.well-known/matrix)))is by far the easiest for traefikI accidentally stripped this out when rearranging, have re-added a clean example again!
@ -101,0 +179,4 @@Before running, create the Caddy network:```bashdocker network create caddyDoes compose not do this automatically?
caddy-docker-proxyrequires an external network that it watches for containers joining. The network needs to exist before you start the compose stack.@ -60,3 +61,1 @@or remove default features; or define all the features in one central workspacecrate that propagate down/up to the other workspace crates. It is a Cargo pitfall,and we'd like to see better developer UX in Rust's Workspaces.The rationale for this is due to Rust / Cargo not supporting ["workspace levelfwiw all these line wraps are causing a bit of diff noise and might mess up the blame a bit
I'm also massively rearranging the file, so I figured there's not much point preserving the exact whitespace here?
fa31f02ef8ad19a9085cad19a9085c2d70c25f202d70c25f20c57c97fad1c57c97fad1cac1c9a352cac1c9a3524fa67b33a6WIP: docs(docker): Restructure deployment guide and add env var referenceto docs(docker): Restructure deployment guide and add env var reference@Jade you are now allowed to review, thank you 😊
I've made a change to the "For existing Traefik setup" example after feedback from River in #COT because the /etc/resolv.conf line caused them trouble - it makes more sense to me to just add a callout underneath.
The deploy preview at https://tcpipuk-docker-docs.continuwuity.pages.dev/reference/environment-variables doesn't seem to have the page coming up in the sidebar at all
Only slight changes. I kind of want to make a lil thing that converts TOML to env vars rather than having all the examples on the env variable guide, but that's way out of scope lol.
@ -62,3 +109,2 @@If the `docker run` command is not suitable for you or your setup, you can also use oneof the provided `docker-compose` files.Docker Compose is the recommended deployment method. These examples includeWe suggest using Docker Compse to help manage your containers
Isn't that what it says? 😕
@ -74,9 +164,17 @@ Depending on your proxy setup, you can use one of the following files:```**Note:** If you need Continuwuity to use your host's DNS resolver instead ofyou can use
suntax to make this pop a bit more.
Should also probably mention why you would want to do that
Also, given it applies to all the compose files, it should probably not be hidden in the collapsed details for one of them
@ -0,0 +3,4 @@Continuwuity can be configured entirely through environment variables, making itideal for containerised deployments and infrastructure-as-code scenarios.This is a convenience reference and may not be exhaustive. TheGiven it's not meant to be exhastive, why not call it a guide?
It doesn't read like a guide to me? I figured a guide would just be the intro about how config options are converted to underscores... I wanted this to be a reference, it's just difficult to ensure it always contains 100% of options, so I clarified that it's there for convenience.
@ -69,0 +141,4 @@services:continuwuity:image: forgejo.ellis.link/continuwuation/continuwuity:latestcommand: --execute "users create-user admin"Hi, I just registered, since I am currently setting continuwuity up via docker compose myself I stumbled across this pr.
This doesn't work since the docker image doesn't have an explicit entry point set so it defaults to bash, instead it should be something like this:
maybe this can be set in the actual Dockerfile instead?
This could probably be fixed by modifying the dockerfile, to aboid having to add config everywhere else. Would be a quick fix
4fa67b33a6612cdc55b3612cdc55b347e661b4ddI think the Configuration Basics should also be edited to include the env var page, with updated env vars too
47e661b4dd5a44f3e5e4Seems like this is blocked until @Jade's requested changes are done. Do you mind unblocking it? Or we can continue on this unmerged PR
I think docs for the new initial registration token flow is needed
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.