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
First-time contributor

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: true changes 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 run docker attach but that's not something I'm experienced with determining how much that might be an issue.

Pull request checklist:

  • This pull request targets the main branch, and the branch is named something other than
    main.
  • I have written an appropriate pull request title and my description is clear.
  • I understand I am responsible for the contents of this pull request.
  • I have followed the contributing guidelines:
<!-- In order to help reviewers know what your pull request does at a glance, you should ensure that 1. Your PR title is a short, single sentence describing what you changed 2. You have described in more detail what you have changed, why you have changed it, what the intended effect is, and why you think this will be beneficial to the project. If you have made any potentially strange/questionable design choices, but didn't feel they'd benefit from code comments, please don't mention them here - after opening your pull request, go to "files changed", and click on the "+" symbol in the line number gutter, and attach comments to the lines that you think would benefit from some clarification. --> 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: true` changes 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 run `docker attach` but that's not something I'm experienced with determining how much that might be an issue. <!-- Example: This pull request allows us to warp through time and space ten times faster than before by double-inverting the warp drive with hyperheated jump fluid, both making the drive faster and more efficient. This resolves the common issue where we have to wait more than 10 milliseconds to engage, use, and disengage the warp drive when travelling between galaxies. --> <!-- Closes: #... --> <!-- Fixes: #... --> <!-- Uncomment the above line(s) if your pull request fixes an issue or closes another pull request by superseding it. Replace `#...` with the issue/pr number, such as `#123`. --> **Pull request checklist:** <!-- You need to complete these before your PR can be considered. If you aren't sure about some, feel free to ask for clarification in #dev:continuwuity.org. --> - [x] This pull request targets the `main` branch, and the branch is named something other than `main`. - [x] I have written an appropriate pull request title and my description is clear. - [x] I understand I am responsible for the contents of this pull request. - I have followed the [contributing guidelines][c1]: - [x] My contribution follows the [code style][c2], if applicable. - [x] I ran [pre-commit checks][c1pc] before opening/drafting this pull request. - [x] I have [tested my contribution][c1t] (or proof-read it for documentation-only changes) myself, if applicable. This includes ensuring code compiles. - [x] My commit messages follow the [commit message format][c1cm] and are descriptive. - [x] I have written a [news fragment][n1] for this PR, if applicable<!--(can be done after hitting open!)-->. <!-- Notes on these requirements: - While not required, we encourage you to sign your commits with GPG or SSH to attest the authenticity of your changes. - While we allow LLM-assisted contributions, we do not appreciate contributions that are low quality, which is typical of machine-generated contributions that have not had a lot of love and care from a human. Please do not open a PR if all you have done is asked ChatGPT to tidy up the codebase with a +-100,000 diff. - In the case of code style violations, reviewers may leave review comments/change requests indicating what the ideal change would look like. For example, a reviewer may suggest you lower a log level, or use `match` instead of `if/else` etc. - In the case of code style violations, pre-commit check failures, minor things like typos/spelling errors, and in some cases commit format violations, reviewers may modify your branch directly, typically by making changes and adding a commit. Particularly in the latter case, a reviewer may rebase your commits to squash "spammy" ones (like "fix", "fix", "actually fix"), and reword commit messages that don't satisfy the format. - Pull requests MUST pass the `Checks` CI workflows to be capable of being merged. This can only be bypassed in exceptional circumstances. If your CI flakes, let us know in matrix:r/dev:continuwuity.org. - Pull requests have to be based on the latest `main` commit before being merged. If the main branch changes while you're making your changes, you should make sure you rebase on main before opening a PR. Your branch will be rebased on main before it is merged if it has fallen behind. - We typically only do fast-forward merges, so your entire commit log will be included. Once in main, it's difficult to get out cleanly, so put on your best dress, smile for the cameras! --> [c1]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md [c2]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/docs/development/code_style.mdx [c1pc]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#pre-commit-checks [c1t]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#running-tests-locally [c1cm]: https://forgejo.ellis.link/continuwuation/continuwuity/src/branch/main/CONTRIBUTING.md#commit-messages [n1]: https://towncrier.readthedocs.io/en/stable/tutorial.html#creating-news-fragments
docs: explain admin console for docker deployments
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
114b935c9f
ky-bean force-pushed docker-admin-console from 114b935c9f
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
to fd062a7bf0
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 3m0s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 13m16s
2026-03-19 21:24:25 +00:00
Compare
Contributor

I 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:

To enable this for Docker deployments, see [the guide](<link>), after which you can use `docker attach` to send commands to the admin console.

Much less noise for people the advice isn't relevant to, in my humble opinion.

I 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: ```md To enable this for Docker deployments, see [the guide](<link>), after which you can use `docker attach` to send commands to the admin console. ``` Much less noise for people the advice isn't relevant to, in my humble opinion.
Author
First-time contributor

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

@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!
ky-bean force-pushed docker-admin-console from fd062a7bf0
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 3m0s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 13m16s
to 64e025a8d4
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been cancelled
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
2026-03-20 20:37:53 +00:00
Compare
docs(docker): Detail how to access the server's console
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been cancelled
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
438fc8aecb
lveneris requested changes 2026-03-22 11:41:12 +00:00
Dismissed
@ -254,1 +254,4 @@
## Accessing the Server's Console
In 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:
Contributor

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:

  • "In order to" is redundant and "To" should usually be preferred
  • The passive voice is not ideal for instructional documents; be as direct as possible
  • Consistency is important, "Docker" should be capitalized everywhere
  • "the containers declaration" should be "the container's declaration"

With that in mind, here is my proposal:

Before you can access the server's console and [send admin commands](../reference/admin/index.md) from the CLI, you need to make the container interactive and allocate a pseudo-tty. For Docker Compose deployments, this means enabling `stdin_open` and `tty` in the container's declaration:

You could also split off the last sentence into its own paragraph, to be consistent with the separation for the docker run method.

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: - "In order to" is redundant and "To" should usually be preferred - The passive voice is not ideal for instructional documents; be as direct as possible - Consistency is important, "Docker" should be capitalized everywhere - "the containers declaration" should be "the container's declaration" With that in mind, here is my proposal: ``` Before you can access the server's console and [send admin commands](../reference/admin/index.md) from the CLI, you need to make the container interactive and allocate a pseudo-tty. For Docker Compose deployments, this means enabling `stdin_open` and `tty` in the container's declaration: ``` You could also split off the last sentence into its own paragraph, to be consistent with the separation for the `docker run` method.
Author
First-time contributor

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!

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!
ky-bean marked this conversation as resolved
@ -255,0 +261,4 @@
homserver:
stdin_open: true
tty: true
<snip>
Contributor

Preferably this should be replaced with something like

# ...

or

# The rest of your declaration goes here

since comments are preferred for elision

Preferably this should be replaced with something like ```yaml # ... ``` or ```yaml # The rest of your declaration goes here ``` since comments are preferred for elision
ky-bean marked this conversation as resolved
@ -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.
Contributor

Was server\'s meant 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

Note that using `CTRL+c` will stop the container. To exit `docker attach`, press `CTRL+p` then `CTRL+q`.
Was `server\'s` meant 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](https://docs.docker.com/reference/cli/docker/container/attach), it would make sense to capitalize the CTRL and put them in inline code segments at least. I might be inclined to suggest ``` Note that using `CTRL+c` will stop the container. To exit `docker attach`, press `CTRL+p` then `CTRL+q`.
Author
First-time contributor

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.

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.
Author
First-time contributor

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.

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.
ky-bean marked this conversation as resolved
@ -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.
Contributor

Continuwuity and Docker should be capitalized here, and there should be a comma on "via Docker, be sure".

Continuwuity and Docker should be capitalized here, and there should be a comma on "via Docker, be sure".
ky-bean marked this conversation as resolved
ky-bean force-pushed docker-admin-console from 438fc8aecb
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been cancelled
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
to 7a8e108589
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been cancelled
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
2026-03-23 00:23:07 +00:00
Compare
docs(docker): update wording, implement suggestions from @lveneris
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been cancelled
Checks / Prek / Pre-commit & Formatting (pull_request) Has been cancelled
Checks / Prek / Clippy and Cargo Tests (pull_request) Has been cancelled
63bba7f418
Author
First-time contributor

@lveneris I've updated following your suggestions, thanks again for the reviews!

@lveneris I've updated following your suggestions, thanks again for the reviews!
lveneris approved these changes 2026-03-23 06:50:04 +00:00
Merge branch 'main' into docker-admin-console
Some checks failed
Documentation / Build and Deploy Documentation (pull_request) Has been skipped
Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m42s
Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m12s
74cfba2437
@ -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.
Owner

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

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
Author
First-time contributor

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.

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

In which case, yes, docker is messing with intended behaviour

In which case, yes, docker is messing with intended behaviour
Author
First-time contributor

Is there anything you'd recommend I add to clarify this discrepancy?

Is there anything you'd recommend I add to clarify this discrepancy?
docs(docker): fix typos (psuedo=>pseudo, decleration=>declaration)
Some checks are pending
Documentation / Build and Deploy Documentation (pull_request) Blocked by required conditions
Checks / Prek / Pre-commit & Formatting (pull_request) Blocked by required conditions
Checks / Prek / Clippy and Cargo Tests (pull_request) Blocked by required conditions
Update flake hashes / update-flake-hashes (pull_request) Blocked by required conditions
Check Changelog / Check for changelog (pull_request_target) Successful in 10s
c9e29937db
ky-bean force-pushed docker-admin-console from c9e29937db
Some checks are pending
Documentation / Build and Deploy Documentation (pull_request) Blocked by required conditions
Checks / Prek / Pre-commit & Formatting (pull_request) Blocked by required conditions
Checks / Prek / Clippy and Cargo Tests (pull_request) Blocked by required conditions
Update flake hashes / update-flake-hashes (pull_request) Blocked by required conditions
Check Changelog / Check for changelog (pull_request_target) Successful in 10s
to 357d9191e3
Some checks are pending
Documentation / Build and Deploy Documentation (pull_request) Blocked by required conditions
Checks / Prek / Pre-commit & Formatting (pull_request) Blocked by required conditions
Checks / Prek / Clippy and Cargo Tests (pull_request) Blocked by required conditions
Check Changelog / Check for changelog (pull_request_target) Successful in 9s
2026-03-28 02:21:05 +00:00
Compare
chore: Add news fragment for #1553
Some checks are pending
Documentation / Build and Deploy Documentation (pull_request) Blocked by required conditions
Checks / Prek / Pre-commit & Formatting (pull_request) Blocked by required conditions
Checks / Prek / Clippy and Cargo Tests (pull_request) Blocked by required conditions
Check Changelog / Check for changelog (pull_request_target) Successful in 10s
b5e46b439e
@ -254,1 +254,4 @@
## Accessing the Server's Console
Before 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.
Owner

Might be worth noting that the console won't open by default unless admin_console_automatic is true in the config

Might be worth noting that the console won't open by default unless `admin_console_automatic` is `true` in the config
Author
First-time contributor

Good point! I've added a note detailing that at the end of that first paragraph.

Good point! I've added a note detailing that at the end of that first paragraph.
docs(docker): Add note for required config setting
Some checks are pending
Documentation / Build and Deploy Documentation (pull_request) Blocked by required conditions
Checks / Prek / Pre-commit & Formatting (pull_request) Blocked by required conditions
Checks / Prek / Clippy and Cargo Tests (pull_request) Blocked by required conditions
Check Changelog / Check for changelog (pull_request_target) Successful in 10s
e3cf878630
Some checks are pending
Documentation / Build and Deploy Documentation (pull_request) Blocked by required conditions
Checks / Prek / Pre-commit & Formatting (pull_request) Blocked by required conditions
Required
Details
Checks / Prek / Clippy and Cargo Tests (pull_request) Blocked by required conditions
Required
Details
Check Changelog / Check for changelog (pull_request_target) Successful in 10s
This pull request is blocked because it's outdated.
Some workflows are waiting to be reviewed.
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 docker-admin-console:ky-bean-docker-admin-console
git switch ky-bean-docker-admin-console
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!1553
No description provided.