docs(docker): Restructure deployment guide and add env var reference #1361

Open
tcpipuk wants to merge 1 commit from tcpipuk/docker-docs into main
Contributor

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:

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: - https://tcpipuk-docker-docs.continuwuity.pages.dev/deploying/docker - https://tcpipuk-docker-docs.continuwuity.pages.dev/development/#building-docker-images - https://tcpipuk-docker-docs.continuwuity.pages.dev/reference/environment-variables
tcpipuk self-assigned this 2026-02-12 12:13:18 +00:00
docs(docker): Restructure deployment guide and add env var reference
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m16s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m39s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 10m6s
fa31f02ef8
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.
@ -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 stop
it.
Replace `matrix.example.com` with your actual server name.
Owner

and admin with your preferred username

and admin with your preferred username
tcpipuk marked this conversation as resolved
@ -60,0 +97,4 @@
volume mount)
- `CONTINUWUITY_ADDRESS` - Bind address (use `0.0.0.0` to listen on all
interfaces)
- `CONTINUWUITY_ALLOW_REGISTRATION` - Set to `false` to prevent open
Owner

uh to prevent any registration

uh to prevent *any* registration
Author
Contributor

I've clarified this, and added a note about reg tokens

I've clarified this, and added a note about reg tokens
tcpipuk marked this conversation as resolved
@ -64,1 +109,3 @@
of the provided `docker-compose` files.
Docker Compose is the recommended deployment method for Continuwuity with a
reverse proxy. These examples include both Continuwuity and a reverse proxy
configured for Matrix federation.
Owner

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

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
Author
Contributor

I've tightened up a few bits including this!

I've tightened up a few bits including this!
tcpipuk marked this conversation as resolved
@ -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 files
Owner

a 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 traefik

a 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 traefik
Author
Contributor

I accidentally stripped this out when rearranging, have re-added a clean example again!

I accidentally stripped this out when rearranging, have re-added a clean example again!
tcpipuk marked this conversation as resolved
@ -101,0 +179,4 @@
Before running, create the Caddy network:
```bash
docker network create caddy
Owner

Does compose not do this automatically?

Does compose not do this automatically?
Author
Contributor

caddy-docker-proxy requires an external network that it watches for containers joining. The network needs to exist before you start the compose stack.

`caddy-docker-proxy` requires an external network that it watches for containers joining. The network needs to exist before you start the compose stack.
tcpipuk marked this conversation as resolved
@ -60,3 +61,1 @@
or remove default features; or define all the features in one central workspace
crate 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 level
Owner

fwiw all these line wraps are causing a bit of diff noise and might mess up the blame a bit

fwiw all these line wraps are causing a bit of diff noise and might mess up the blame a bit
Author
Contributor

I'm also massively rearranging the file, so I figured there's not much point preserving the exact whitespace here?

I'm also massively rearranging the file, so I figured there's not much point preserving the exact whitespace here?
tcpipuk marked this conversation as resolved
tcpipuk force-pushed tcpipuk/docker-docs from fa31f02ef8
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m16s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m39s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 10m6s
to ad19a9085c
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m20s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 1m52s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 8m56s
2026-02-12 12:47:52 +00:00
Compare
tcpipuk force-pushed tcpipuk/docker-docs from ad19a9085c
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m20s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 1m52s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 8m56s
to 2d70c25f20
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m36s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 1m58s
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
2026-02-12 12:59:11 +00:00
Compare
tcpipuk force-pushed tcpipuk/docker-docs from 2d70c25f20
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m36s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 1m58s
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
to c57c97fad1
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m40s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m11s
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
2026-02-12 13:02:00 +00:00
Compare
tcpipuk force-pushed tcpipuk/docker-docs from c57c97fad1
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m40s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m11s
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
to cac1c9a352
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m23s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 1m48s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 8m32s
2026-02-12 13:07:11 +00:00
Compare
tcpipuk force-pushed tcpipuk/docker-docs from cac1c9a352
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m23s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 1m48s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 8m32s
to 4fa67b33a6
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m21s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m0s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 8m33s
2026-02-12 13:25:09 +00:00
Compare
tcpipuk changed title from WIP: docs(docker): Restructure deployment guide and add env var reference to docs(docker): Restructure deployment guide and add env var reference 2026-02-12 13:36:37 +00:00
Author
Contributor

@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.

@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.
Owner

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

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
Jade left a comment
Owner

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.

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 one
of the provided `docker-compose` files.
Docker Compose is the recommended deployment method. These examples include
Owner

We suggest using Docker Compse to help manage your containers

We suggest using Docker Compse to help manage your containers
Author
Contributor

Isn't that what it says? 😕

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 of
Owner

you can use

:::note Title
text 
:::

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

you can use ``` :::note Title text ::: ``` suntax to make this pop a bit more. Should also probably mention [why you would want to do that](https://continuwuity.org/troubleshooting.html#potential-dns-issues-when-using-docker) Also, given it applies to all the compose files, it should probably not be hidden in the collapsed details for one of them
tcpipuk marked this conversation as resolved
@ -0,0 +3,4 @@
Continuwuity can be configured entirely through environment variables, making it
ideal for containerised deployments and infrastructure-as-code scenarios.
This is a convenience reference and may not be exhaustive. The
Owner

Given it's not meant to be exhastive, why not call it a guide?

Given it's not meant to be exhastive, why not call it a guide?
Author
Contributor

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.

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:latest
command: --execute "users create-user admin"
First-time contributor

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:

image: forgejo.ellis.link/continuwuation/continuwuity:latest
entrypoint: conduwuit
command: --execute "users create-user admin"

maybe this can be set in the actual Dockerfile instead?

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: ```yaml image: forgejo.ellis.link/continuwuation/continuwuity:latest entrypoint: conduwuit command: --execute "users create-user admin" ``` maybe this can be set in the actual Dockerfile instead?
Owner

This could probably be fixed by modifying the dockerfile, to aboid having to add config everywhere else. Would be a quick fix

This could probably be fixed by modifying the dockerfile, to aboid having to add config everywhere else. Would be a quick fix
tcpipuk force-pushed tcpipuk/docker-docs from 4fa67b33a6
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m21s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m0s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 8m33s
to 612cdc55b3
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Successful in 2m26s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 5m45s
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
2026-02-13 06:35:47 +00:00
Compare
tcpipuk force-pushed tcpipuk/docker-docs from 612cdc55b3
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Successful in 2m26s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 5m45s
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
to 47e661b4dd
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m57s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m36s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 14m41s
2026-02-13 06:46:45 +00:00
Compare
Contributor

I think the Configuration Basics should also be edited to include the env var page, with updated env vars too

I think the [Configuration Basics](https://tcpipuk-docker-docs.continuwuity.pages.dev/configuration.html#basics) should also be edited to include the env var page, with updated env vars too
nex approved these changes 2026-02-23 17:56:47 +00:00
nex force-pushed tcpipuk/docker-docs from 47e661b4dd
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 1m57s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 2m36s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 14m41s
to 5a44f3e5e4
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 2m26s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m36s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 37m6s
2026-02-23 17:57:42 +00:00
Compare
nex scheduled this pull request to auto merge when all checks succeed 2026-02-23 17:57:59 +00:00
Contributor

Seems 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

Seems 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
All checks were successful
Documentation / Build and Deploy Documentation (pull_request) Successful in 2m26s
Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m36s
Required
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 37m6s
Required
Details
This pull request has changes requested by an official reviewer.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin tcpipuk/docker-docs:tcpipuk/docker-docs
git switch tcpipuk/docker-docs
Sign in to join this conversation.
No reviewers
No milestone
No project
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
No description provided.