docs: Explain how to enable sending admin commands to the server console for docker deployments #1553
No reviewers
Labels
No labels
Blocked
Bug
Changelog
Added
Changelog
Missing
Changelog
None
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
Merge
Merge/Manual
Merge/Squash
Meta
Meta/CI
Meta/Packaging
Priority
Blocking
Priority
High
Priority
Low
Security
Status
Confirmed
Status
Duplicate
Status
Invalid
Status
Needs Investigation
Support
Wont fix
old/ci/cd
old/rust
No milestone
No project
No assignees
6 participants
Notifications
Due date
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.
@ky-bean, I'm opening #1594 which will likely override your additions in this PR. Ideally I'd like to include your changes somewhere in the new restructured page (if it's approved that is). I can add them myself and put you as
Co-authored-by:andCo-committed-by:if that's okayMaintainers please let us know how to coordinate.
@stratself if you want you can cherry-pick changes.