From 6915bca11c32e8af24b4f4ad11ca7d6aabfc9ced Mon Sep 17 00:00:00 2001 From: stratself Date: Fri, 31 Jul 2026 11:17:21 +0000 Subject: [PATCH] docs(dns): Add workaround notes for connecting to containers via IPs * docs(appservices): Fix registration command and also add Docker DNS caveats * docs(docker): A word --- docs/appservices.mdx | 30 ++++++++++------ docs/deploying/docker.mdx | 2 +- docs/guides/dns.mdx | 72 ++++++++++++++++++++++++++++++--------- 3 files changed, 75 insertions(+), 29 deletions(-) diff --git a/docs/appservices.mdx b/docs/appservices.mdx index 5c22b7fa9..b59beb499 100644 --- a/docs/appservices.mdx +++ b/docs/appservices.mdx @@ -20,17 +20,19 @@ ## Set up the appservice - general instructions registered on the homeserver automatically joins it. Then send a message into the room like this: - !admin appservices register - ``` - paste - the - contents - of - the - yaml - registration - here - ``` +~~~txt +!admin appservices register +``` +paste +the +contents +of +the +yaml +registration +here +``` +~~~ You can confirm it worked by sending a message like this: `!admin appservices list` @@ -51,3 +53,9 @@ ### Remove an appservice `!admin appservices unregister ` where `` one of the output of `appservices list`. + +## Caveats + +### Docker DNS + +If you follow the [DNS tuning guide](./guides/dns.mdx#for-docker-users) and mount a custom `/etc/resolv.conf`, you may not be able to connect to appservices containers via hostname. Follow the workaround [there](./guides/dns.mdx#breaking-resolution-with-container-hostnames) to connect to your appservice via static IPs. diff --git a/docs/deploying/docker.mdx b/docs/deploying/docker.mdx index 62819a2ad..69d184015 100644 --- a/docs/deploying/docker.mdx +++ b/docs/deploying/docker.mdx @@ -63,7 +63,7 @@ ### Choose Your Reverse Proxy These examples include reverse proxy configurations for Matrix federation, which will route your Matrix domain (and optionally .well-known paths) to Continuwuity. :::note Docker DNS Performance -Docker's default DNS resolver are known to [cause timeout issues](../troubleshooting#dns-issues) for Matrix federation. To bypass it and use a more performant resolver, mount a custom `/etc/resolv.conf` config file into the Continuwuity container. +Docker's default DNS resolver are known to [cause timeout issues](../troubleshooting#dns-issues) for Matrix federation. To bypass it and use a more performant resolver, we will mount a custom `/etc/resolv.conf` config file into the Continuwuity container. ```yaml title='docker-compose.yml' services: diff --git a/docs/guides/dns.mdx b/docs/guides/dns.mdx index 4764904f7..cdcbfb5b5 100644 --- a/docs/guides/dns.mdx +++ b/docs/guides/dns.mdx @@ -8,7 +8,7 @@ # DNS Tuning (recommended) ## Overview -For generic deployments, install your resolver of choice and configure `/etc/resolv.conf` to point to it. The resolver should ideally reside on the same host as Continuwuity. +For generic deployments, install your resolver of choice and configure your host system's `/etc/resolv.conf` to point to it. The resolver should ideally reside on the same host as Continuwuity. ```txt title="/etc/resolv.conf" nameserver 127.0.0.1 @@ -18,7 +18,7 @@ ## Overview ### 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. +By default, Docker bridge networks uses a non-performant resolver to intercept and respond to container hostnames. **This resolver should also be avoided**. Instead, mount a custom `/etc/resolv.conf` file into the container, and hardcode a resolver address to bypass Docker's. It is recommended to run a dedicated resolver container for Continuwuity, as to separate from the host's resolver setup. To do this, create a custom bridge network and IP range, and explicitly define an IP address for the resolver container. @@ -27,23 +27,29 @@ ### For Docker users ```yaml title="docker-compose.yml" networks: - matrix_net: + + # re-use the `proxy` network, as shown in Docker deployment docs, + # with a custom subnet + # https://continuwuity.org/deploying/docker#choose-your-reverse-proxy + proxy: ipam: driver: default config: - subnet: "10.10.10.0/24" services: - homeserver: - # ... - volume: - - ./continuwuity-resolv.conf:/etc/resolv.conf:ro + homeserver: + # ... + volume: + - ./continuwuity-resolv.conf:/etc/resolv.conf:ro + networks: + - proxy - unbound: - # ... - networks: - matrix_net: - ipv4_address: 10.10.10.20 + unbound: + # ... + networks: + proxy: + ipv4_address: 10.10.10.20 ``` ```txt title="continuwuity-resolv.conf" @@ -52,9 +58,41 @@ ### For Docker users +:::warning Breaking resolution with container hostnames + +By mounting a custom `/etc/resolv.conf`, you won't be able to connect to other container via their hostnames, such as [appservice](../appservices.mdx) in the same Docker network. To work around this, also force your appservice to use a static IP address, and refer to such IP during registration. + +
+Example Docker deployment with an appservice + +```yaml title="docker-compose.yml" +# ... other parts of compose file ... + + appservice: + # ... + networks: + proxy: + ipv4_address: 10.10.10.30 +``` + +~~~txt +!admin appservices register + +``` +id: appservice-name +url: http://10.10.10.30:29318 +# rest of the registration file +``` + +~~~ + +
+ +::: + ### For IPv4-only users -If you don't have IPv6 connectivity, changing `ip_lookup_strategy` to only resolve for IPv4 will reduce unnecessary AAAA queries. +If you don't have IPv6 connectivity, change `ip_lookup_strategy` to `1`, in order to only resolve for IPv4 and remove unnecessary AAAA queries. ```toml title="continuwuity.toml" [global] @@ -74,11 +112,11 @@ ## Unbound - Increase `discard-timeout` to something like `4800` to wait longer for upstream resolvers, as recursion can take a long time to respond to some domains. Continuwuity default to `dns_timeout = 10` seconds, so dropping requests early would lead to unnecessary retries and/or failures. -### Recursion versus forwarding +### Using a forwarder (optional) -Unbound by default employs **recursive resolution** and contacts many servers around the world. While this allows updated and authoritative answers and are generally viable for most users, sometimes these recursive queries can be too slow to fully resolve. As an alternative, you can consider **forwarding** your queries to public resolvers, and benefit from faster responses from their CDNs. +Unbound by default employs **recursive resolution** and contacts many nameservers around the world. While this is generally viable for most users, sometimes these recursive queries can be too slow to fully resolve. As an alternative, you may consider **forwarding** your queries to public resolvers, and benefit from faster responses from their CDNs. -Do note that most popular upstreams (such as Google DNS or Quad9) employ IP ratelimiting, so a generous cache is still needed to avoid making too many queries. +However, do note that most popular upstreams (such as Google DNS or Quad9) employ IP ratelimiting, so a generous Unbound cache is still needed to avoid making too many queries. If you want to use forwarders, configure it as follows: @@ -144,7 +182,7 @@ ### Technitium DNS ## Testing -As a rough stress test, you can run `!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 a rough stress test, you can run `!admin query resolver flush-cache -a` or `!admin server clear-caches` to clear your destinations cache - this will then trigger a netburst of DNS queries. If your resolver can handle this load without problem, then it should be ready for regular Continuwuity activity. To test connectivity against a specific server, use `!admin debug ping ` and `!admin debug resolve-true-destination `.