continuwuation/continuwuity
continuwuation/continuwuity
13
79
Fork 85
Code Issues 117 Pull requests 44 Releases 27 Packages 3 Activity Actions 11

Coordinate docs refactor for Deploying, Configuration, and Reference sections #1508

New issue
Open
opened 2026-03-08 08:05:22 +00:00 by stratself · 1 comment
stratself commented 2026-03-08 08:05:22 +00:00
Contributor
Copy link

After #1361 was merged, there is a more solid foundation to continue refactoring docs for multiple sections. This issue is for brainstorming stuff where I intend to work upon, open for public opinions.

The point is to put them into appropriately-ordered PRs to avoid conflicts and reflect changes carefully. Ideally, they should result in clearer docs with less repeated parts and less cruft. Comments on how best to do these change controls are appreciated!

Configuration section

These items can go into its own thing at docs-configuration-fixes. I think I'll start on this one since it's the least intrusive:

Deploying section

  • First, unify on a standardized way to deploy Continuwuity. I suggest the "default" way is to use no .well-knowns, and expose the reverse proxy for both :443 and :8448. Delegation/split-domain can go in its own page.
  • Second, unify on the reverse proxy choice. I'll go with an order of Caddy > Traefik > nginx (if available), since they are most available with c10y users.

These items can be its own PR i.e. docs-docker-fixes:

  • Rearrange docker page to 3 main section: Image, Docker (Quick Start), Docker-Compose. The "Docker (Quick Start)" section should be short as Compose is preferred
  • 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

These can go into one PR i.e. docs-new-initial-flow:

Lastly, there could be a potential PR to improve some stuff in the Generic deployment page docs-generic-deployment-fixes:

  • Minimize build instructions or move it somewhere else
  • Improve the Other Reverse Proxies section to also include ports and stuff - this will be highly referenced from other pages

I prefer writing the docker + generic fixes first for clarity, but new initial flow is more important. Question on which to start first needs answer

Other stuff

  • A "What's next" section for both docker/generic pages should be added/fixed
  • DNS tuning PR will also need to relink into the Docker page, as well as rewrite the Troubleshooting pages
After #1361 was merged, there is a more solid foundation to continue refactoring docs for multiple sections. This issue is for brainstorming stuff where I intend to work upon, open for public opinions. The point is to put them into appropriately-ordered PRs to avoid conflicts and reflect changes carefully. Ideally, they should result in clearer docs with less repeated parts and less cruft. Comments on how best to do these change controls are appreciated! ## Configuration section These items can go into its own thing at `docs-configuration-fixes`. I think I'll start on this one since it's the least intrusive: - [ ] Refactor [configuration](https://continuwuity.org/configuration.html) page to prioritize env var use and unrecommend passing CLI options - [ ] Move the env var [prefix stuff from Env Var page](https://continuwuity.org/reference/environment-variables#prefix-system) to the Configuration page, and announce the order there ## Deploying section - First, unify on a standardized way to deploy Continuwuity. I suggest the "default" way is to use no .well-knowns, and expose the reverse proxy for both :443 and :8448. Delegation/split-domain can go in its own page. - Second, unify on the reverse proxy choice. I'll go with an order of Caddy > Traefik > nginx (if available), since they are most available with c10y users. These items can be its own PR i.e. `docs-docker-fixes`: - [ ] Rearrange [docker](https://continuwuity.org/deploying/docker) page to 3 main section: Image, Docker (Quick Start), Docker-Compose. The "Docker (Quick Start)" section should be short as Compose is preferred - [ ] 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 These can go into one PR i.e. `docs-new-initial-flow`: - [ ] Rewrite [docker](https://continuwuity.org/deploying/docker) and [generic](https://continuwuity.org/deploying/generic) instructions to match the new registration flow from #1367 Lastly, there could be a potential PR to improve some stuff in the Generic deployment page `docs-generic-deployment-fixes`: - [ ] Minimize build instructions or move it somewhere else - [ ] Improve the [Other Reverse Proxies](https://continuwuity.org/deploying/generic.html#other-reverse-proxies) section to also include ports and stuff - this will be highly referenced from other pages I prefer writing the docker + generic fixes first for clarity, but new initial flow is more important. Question on which to start first needs answer ## Other stuff - A "What's next" section for both docker/generic pages should be added/fixed - DNS tuning PR will also need to relink into the Docker page, as well as rewrite the Troubleshooting pages
stratself commented 2026-03-10 09:23:10 +00:00
Author
Contributor
Copy link

docs-new-initial-flow can somewhat be unprioritized as the !admin users create-user workflow still works

`docs-new-initial-flow` can somewhat be unprioritized as the `!admin users create-user` workflow still works
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
renovate/lock-file-maintenance
aranje/illegal-car-mods
renovate/recaptcha-verify-0.x
jade/community-guidelines
nex/experiment/push-gateway-logs
ginger/msc3575-obliteration
ginger/password-reset
renovate/docker-setup-qemu-action-4.x
renovate/rand_core-0.x
renovate/serde_html_form-0.x
renovate/reqwest-0.x
renovate/github-actions-non-major
nex/feat/block-busted-rooms
nex/fix/informative-startup-errs
ginger/no-left-room-initial-sync
nex/feat/policy-servers-2-electric-boogaloo
jade/docker-entrypoint
jade/dehydrated-devices
ginger/complement-fixes
nex/fix/stale-destination-cache
nex/experiment/sync-mutex
tcpipuk/docker-docs
jade/snafu
jade/rand-update
nex/stateres-refactor
ginger/779-in-troubleshooting
jade/liveit-guide
jade/http3
nex/feat/admin-hide-empty-rooms
ginger/oobe
nex/fix/debian-thingy
jade/ldap-admin-check
nex/fix/remote-restricted-joins
nex/feat/msc4406-sender-ignored
jade/deadlock-detection
nex/feat/room-shutdown
jade/get-started
jade/docs-guide
ginger/fix-local-invites
nex/fix/tpi
nex/feat/room-deletion
nex/feat/msc4322-media-redaction
ginger/stitched-order
jade/build-info
ginger/deps/update-rspress
jade/admin-announce-improvements
ginger/xtask-improvements
jade/improve-admin-config-display
nex/fix/better-stateres-error-logs
jade/sender-timeouts
nex/feat/custom-v12-room-ids
ginger/update-metadata
nex/feat/admin-force-logout
tom/max-perf-docs
nex/fix/invalid-appservice-reg
nex/feat/antispam
nex/feat/account-locking
jade/logging-cleanup
jade/remove-legacy-appservice-auth
nex/fix/key-query
jade/update-prek
nex/fix/room-summaries
ginger/restrict-admin-commands
ginger/enable-console-by-default
jade/tag-fixes
jade/otlp
nex/meta/pull-req-template
nex/fix/fed-invite-compliance
nex/feat/build-commit
nex/feat/join-logging
jade/mailmap-updates
jade/hack-ci-tmp
jade/v12-stable
jade/relations
ginger/database-refactor
jade/fix-ldap-uiaa
nex/fix/validation
ginger/nuke-invalid-msc4133-fields-in-migration
ginger/downgrade-artifact-actions
oddlid/reload-fix
jade/fix-assert
ginger/sync-v3-cleanup
ginger/remove-absolute-action-urls
jade/website
nex/fix/backoff
ginger/fix-mdbook-for-0.5
ginger/no-docker-on-prs
backport/v0.5.0-rc.8-1
nex/fed-improvements
jade/rust-1.90
jade/mirror-dockerhub
jade/clippy-fixes
jade/fix-support
jade/clean-images
jade/wal-compression-type
jade/flake-clone
ginger/upload-rpms-on-schedule
nex/fix/incoming-fetch
nex/fix/upgrade
tom/ci-fedora-rpm
jade/ci-release-fix
jade/rocksdb-10-5
ginger/fix-msc4133-migration
ginger/migrate-busted-tz
hydra/public
nex/feat/manual-extremities
nex/feat/async-media
nex/feat/fast-joins-hack-do-not-use-DO-NOT-USE
nex/feat/better-logging
trigger-ci-so-latest-isnt-on-illegal-car-mods
nex/feat/pins-backfill
jade/tuwunel-2025-06-old
jade/ai-slop-db-docs
nex/fix-create-auth
jade/version-stats
jade/read-receipts
jade/rust-toolchain-no-targets
jade/logging-features
jade/syncv5-typing
jade/msc2815
jade/purge-sync-tokens
morguldir/see-eye
jade/css-small-screen
nex/wip-751
tuwunel-rebase
test
oddlid/rename-admin-room-bot
strawberry/nix-ci-stuff
strawberry/valgrind
phonemain
strawberry/morgs-snake-sync-jason-main
newer-media-endpoints
folly-coroutines-async-io
federation-retry-timer-port
bad-attempt-at-extracting-homeserver-signing-key
room-deletion-attempt-do-not-use
v0.5.6
v0.5.6-alpha
v0.5.5
v0.5.4
v0.5.3
v0.5.2
v0.5.1
v0.5.0
v0.5.0-rc.8.1
v0.5.0-rc.8
v0.5.0-rc.7
v0.5.0-rc.6
v0.5.0-rc.5
v0.5.0-rc4
v0.5.0-rc3
v0.5.0-rc2
v0.5.0-rc
v0.4.7-rc
v0.4.6
v0.4.6-rc
v0.4.5-rc
v0.4.5
v0.4.4
v0.4.3
v0.4.2
v0.4.1
v0.3.4
v0.3.3
v0.3.2
v0.3.1
v0.3.0
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

  
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
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#1508
No description provided.