WIP: docs: Add DNS tuning guide #1601

stratself · 2026-04-01T05:33:33Z

stratself commented

2026-04-01 05:33:33 +00:00

This pull request adds a DNS tuning guide page for Continuwuity, targetting Unbound. It recommends best practices.

You can see a preview of it here:

TODOS:

Rewrite the troubleshooting page section to simplify wording and reflink to this new page.
Link other pages (e.g. Docker next steps, performance tuning) to this page (in other PRs)

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:
- My contribution follows the code style, if applicable.
- I ran pre-commit checks before opening/drafting this pull request.
- I have tested my contribution (or proof-read it for documentation-only changes)
  myself, if applicable. This includes ensuring code compiles.
- My commit messages follow the commit message format and are descriptive.
- I have written a news fragment for this PR, if applicable.

This pull request adds a DNS tuning guide page for Continuwuity, targetting Unbound. It recommends best practices. You can see a preview of it here: - https://muc.muoi.me/advanced/dns.html - https://muc.muoi.me/troubleshooting.html#dns-issues TODOS: - [x] Rewrite the [troubleshooting page section](https://continuwuity.org/troubleshooting#dns-issues) to simplify wording and reflink to this new page. - [ ] Link other pages (e.g. Docker next steps, performance tuning) to this page (in other PRs)     **Pull request checklist:**  - [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.  [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

stratself added 2 commits

2026-04-01 05:33:33 +00:00

docs(dns): Initialize dns docs b53ebdb7e1

docs(dns): Add main content

Check Changelog / Check for changelog (pull_request_target) Successful in 16s

Details

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 3m9s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 13m13s

Details

6b771dcc9a

stratself added 1 commit

2026-04-01 09:28:58 +00:00

docs(dns): Clarity changes and some additions

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 11s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m55s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m37s

Details

868a982cbb

stratself added 1 commit

2026-04-01 09:54:33 +00:00

docs(troubleshooting): shorten dns section and link to dns tuning guide

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 10s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Failing after 2m54s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 13m4s

Details

f1a4cb2b3e

theSuess reviewed

2026-04-01 15:00:24 +00:00

theSuess left a comment

First-time contributor

Only checked for technical input for now since I know that drive-by reviews by external people can be annoying for maintainers 😅

One option that could also be useful for tuning (esp. on kubernetes) is ndots as having a high value here will cause lookups of external domains with the search domain appended (e.g matrix.org -> matrix.org.my.network)

If you want to, I can take a look at the wording and instruction text as well (I often do this as part of my dayjob) but I didn't want to spam this without asking first :)

Only checked for technical input for now since I know that drive-by reviews by external people can be annoying for maintainers 😅 One option that could also be useful for tuning (esp. on kubernetes) is [ndots](https://www.man7.org/linux/man-pages/man5/resolv.conf.5.html#:~:text=see%20resolver%283%29%29%2E-,ndots%3A) as having a high value here will cause lookups of external domains with the search domain appended (e.g `matrix.org` -> `matrix.org.my.network`) If you want to, I can take a look at the wording and instruction text as well (I often do this as part of my dayjob) but I didn't want to spam this without asking first :)

docs/advanced/dns.mdx

					
				@ -0,0 +18,4 @@

				### For Docker users

				Docker bridge networks uses a non-performant resolver to intercept and respond to container hostnames, and **this should also be avoided**. Instead, mount a custom `/etc/resolv.conf` file into the container, and hardcode a resolver address to bypass Docker's.

Docker supports adhoc generation of resolv.conf. This can also be done using docker compose which removes the need for a volume mount/extra file to manage:
https://docs.docker.com/reference/compose-file/services/#dns

Docker supports adhoc generation of `resolv.conf`. This can also be done using docker compose which removes the need for a volume mount/extra file to manage: https://docs.docker.com/reference/compose-file/services/#dns

This doesn't seem doable with custom bridge networks

~$ docker network create testing
<some-long-id>
~$ docker run --rm -it --net testing --dns 1.1.1.1 alpine cat /etc/resolv.conf

$ docker run --rm -it --net testing --dns 1.1.1.1 alpine cat /etc/resolv.conf
# Generated by Docker Engine.
# This file can be edited; Docker Engine will not make further changes once it
# has been modified.

nameserver 127.0.0.11
options use-vc ndots:0

# Based on host file: '/etc/resolv.conf' (internal resolver)
# ExtServers: [1.1.1.1]
# Overrides: [nameservers]
# Option ndots from: internal

Same behavior with Podman, though they have the --disable-dns flag. It probably relates to this longstanding issue. Hence the resolv.conf mount workaround

Do let me know if you find alternative solutions to this tho. It will also help #1594

This doesn't seem doable with custom bridge networks ``` ~$ docker network create testing <some-long-id> ~$ docker run --rm -it --net testing --dns 1.1.1.1 alpine cat /etc/resolv.conf $ docker run --rm -it --net testing --dns 1.1.1.1 alpine cat /etc/resolv.conf # Generated by Docker Engine. # This file can be edited; Docker Engine will not make further changes once it # has been modified. nameserver 127.0.0.11 options use-vc ndots:0 # Based on host file: '/etc/resolv.conf' (internal resolver) # ExtServers: [1.1.1.1] # Overrides: [nameservers] # Option ndots from: internal ``` Same behavior with Podman, though they have the `--disable-dns` flag. It probably relates to this longstanding [issue](https://github.com/moby/moby/issues/19474). Hence the resolv.conf mount workaround Do let me know if you find alternative solutions to this tho. It will also help #1594

docs/advanced/dns.mdx

					
				@ -0,0 +147,4 @@

				## Testing

				As a rough stress test, you can issue `!admin query resolver flush-cache -a` or `!admin server clear-caches` to trigger a netburst of DNS queries. If your resolver can handle these loads without problem, then it should be ready for regular Continuwuity activity.

As you already mentioned in chat, these commands would be great in the troubleshooting guide

👍 1

I added them to latest commit. Here's a rendered version

Not sure if the docs structure is optimal, let me know

I added them to [latest commit](https://forgejo.ellis.link/continuwuation/continuwuity/pulls/1601/commits/928ac8d9c542b65c46aeb51aa16acdbca2c78672). Here's a [rendered version](https://muc.muoi.me/troubleshooting.html#intermittent-federation-failures-to-a-specific-server) Not sure if the docs structure is optimal, let me know

stratself commented

2026-04-01 17:22:04 +00:00

@theSuess Many thanks for looking over the PR, I'm also just another drive-by contributor who wanna help with docs, so feel free to nag me for improvements over your free time :D

stratself added 1 commit

2026-04-04 08:13:56 +00:00

docs(troubleshooting): Add section on intermittent fed failures

Documentation / Build and Deploy Documentation (pull_request) Has been skipped

Details

Check Changelog / Check for changelog (pull_request_target) Successful in 10s

Details

Checks / Prek / Pre-commit & Formatting (pull_request) Successful in 3m6s

Details

Checks / Prek / Clippy and Cargo Tests (pull_request) Successful in 12m55s

Details

928ac8d9c5