docs: Explain how to enable sending admin commands to the server console for docker deployments #1553
Open
ky-bean
wants to merge 6 commits from
ky-bean/continuwuity:docker-admin-console into main
pull from: ky-bean/continuwuity:docker-admin-console
merge into: continuwuation:main
continuwuation:main
continuwuation:aranje/illegal-car-mods
continuwuation:nex/feat/policy-servers-2-electric-boogaloo
continuwuation:nex/chore/lettre-use-ring
continuwuation:renovate/node-patch-updates
continuwuation:ginger/email-support
continuwuation:renovate/cargo-bins-cargo-binstall-1.x
continuwuation:jade/community-guidelines
continuwuation:nex/fix/federation-format
continuwuation:jade/git-deps-updates
continuwuation:jade/pin-gh-actions
continuwuation:jade/changelog-check
continuwuation:jade/rust-1-92
continuwuation:ginger/password-reset
continuwuation:nex/experiment/push-gateway-logs
continuwuation:ginger/msc3575-obliteration
continuwuation:renovate/rand_core-0.x
continuwuation:renovate/serde_html_form-0.x
continuwuation:renovate/reqwest-0.x
continuwuation:renovate/github-actions-non-major
continuwuation:nex/feat/block-busted-rooms
continuwuation:nex/fix/informative-startup-errs
continuwuation:ginger/no-left-room-initial-sync
continuwuation:jade/docker-entrypoint
continuwuation:jade/dehydrated-devices
continuwuation:ginger/complement-fixes
continuwuation:nex/fix/stale-destination-cache
continuwuation:nex/experiment/sync-mutex
continuwuation:tcpipuk/docker-docs
continuwuation:jade/snafu
continuwuation:jade/rand-update
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
No reviewers
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
Issues related to end to end encryption
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
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
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!1553
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "ky-bean/continuwuity:docker-admin-console"
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?
This pull request adds a note to the Admin Command Reference page of the docs adding info about how docker deployments should be setup to enable correctly attaching to the server's console, which then enables sending admin commands to the server console as expected.
The only open question I have regarding this is whether or not the
-it/std_open: true&tty: truechanges for docker should be included by default in the docker deployment docs. There could be an argument about system security being at risk with the server's console tty being available to any user with permissions to rundocker attachbut that's not something I'm experienced with determining how much that might be an issue.Pull request checklist:
mainbranch, and the branch is named something other thanmain.myself, if applicable. This includes ensuring code compiles.
114b935c9ffd062a7bf0I think most of this guidance should go in the Docker deployment docs, since it's Docker specific. Maybe there should be a warning on one of the pages that you need to add those options in order to use the admin console. You can then link back to that from the admin commands reference, wth a note like this:
Much less noise for people the advice isn't relevant to, in my humble opinion.
@lveneris I went back n forth on where I thought the comment should go, linking in the admin reference to the docker docs makes sense, I'll make that change!
fd062a7bf064e025a8d4@ -254,1 +254,4 @@## Accessing the Server's ConsoleIn order to enable access the server's console to [send admin commands](../reference/admin/index.md) from the CLI, the docker deployment will need to be made interactive and allocate a psuedo-tty. For deployments via Docker Compose, this means adding `stdin_open: true` and `tty: true` to the containers decleration:You missed a "to" between "access the", but I would propose changing the structure of this.
Some notes for your reference, since I don't really like to throw suggestions at people without giving them anything to learn from:
With that in mind, here is my proposal:
You could also split off the last sentence into its own paragraph, to be consistent with the separation for the
docker runmethod.Thank you for taking the time to provide constructive criticism, I definitely don't write documentation enough (or really do much writing at all..) I appreciate receiving the guidance on the right language to use and how to construct Actually Helpful documentation!
@ -255,0 +261,4 @@homserver:stdin_open: truetty: true<snip>Preferably this should be replaced with something like
or
since comments are preferred for elision
@ -255,0 +266,4 @@If you choose to deploy via `docker run`, then add the flags `-i`/`--interactive` and `-t`/`--tty` to the command.From there you can access the server's console by running `docker attach <container-name>`, which will show the server\'s prompt `uwu> `. To exit `docker attach` press ctrl+p then ctrl+q.Was
server\'smeant to be escaped? This does not appear anywhere else.I am also not sure of any existing precedent for the style of writing keybinds into the docs, but deferring to the Docker docs page, it would make sense to capitalize the CTRL and put them in inline code segments at least.
I might be inclined to suggest
Regarding the escaped single-quote, I think my brain probably just crossed some wires and thought I was writing the backtick and needed to escape it to render correctly in markdown, it can be removed.
Ah, going back in and editing the docs I realize now why I escaped the quote mark, because these files have '.mdx' extensions my editor wasn't registering them as markdown files and so the single quotes were being interpreted as a string by the code highlighter.
@ -8,3 +8,3 @@* All commands listed here may be used by server administrators in the admin room by sending them as messages.* If the `admin_escape_commands` configuration option is enabled, server administrators may run certain commands in public rooms by prefixing them with a single backslash. These commands will only run on _their_ homeserver, even if they are a member of another homeserver's admin room. Some sensitive commands cannot be used outside the admin room and will return an error.* All commands listed here may be used in the server's console, if it is enabled. Commands entered in the console do not require the `!admin` prefix.* All commands listed here may be used in the server's console, if it is enabled. Commands entered in the console do not require the `!admin` prefix. If continuwuity is deployed via docker be sure to set the appropriate options detailed in [the docker deployment guide](../../deploying/docker.mdx#accessing-the-servers-console) to enable access to the server's console.Continuwuity and Docker should be capitalized here, and there should be a comma on "via Docker, be sure".
438fc8aecb7a8e108589@lveneris I've updated following your suggestions, thanks again for the reviews!
@ -255,0 +270,4 @@From there you can access the server's console by running `docker attach <container-name>`, which will show the server's prompt `uwu> `.Note that using `CTRL+c` within `docker attach`'s context will forward the signal to the server, stopping it. To exit `docker attach` press `CTRL+p` then `CTRL+q`. See [Docker's reference](https://docs.docker.com/reference/cli/docker/container/attach/) for more information.At least on podman, this forwards to the container but opens the console as expected. Does docker do weird things here? stopping the server should be triggered by ctrl+/ iirc
I'm not entirely sure what you're asking about here... The instructions as written work for plain docker deployments, I can access the container's console and send admin commands as intended, and the sequence CTRL+P CTRL-Q exits the attached session. CTRL+C will shutdown the server bc SIGINT is forwarded through the attachment to the server process (or the console process if it's seperate). CTRL+C is mentioned here because the naive person (AKA me before looking it up) will try to use CTRL+C to exit the attached session, and will be left with surprise downtime instead.
In which case, yes, docker is messing with intended behaviour
Is there anything you'd recommend I add to clarify this discrepancy?
c9e29937db357d9191e3@ -254,1 +254,4 @@## Accessing the Server's ConsoleBefore you can access the server's console and [send admin commands](../reference/admin/index.md) from the CLI, you will need to make the container interactive and allocate a pseudo-tty.Might be worth noting that the console won't open by default unless
admin_console_automaticistruein the configGood point! I've added a note detailing that at the end of that first paragraph.
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.