dandri/continuwuity
1
0 Fork 0
mirror of https://forgejo.ellis.link/continuwuation/continuwuity/ synced 2026-10-23 11:22:25 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs(dns): Add workaround notes for connecting to containers via IPs

Browse Source 
* docs(appservices): Fix registration command and also add Docker DNS caveats
* docs(docker): A word
This commit is contained in:
stratself authored and Ellis Git committed 2026-08-05 18:00:11 +00:00
1 parent 519ebc96cc
commit 6915bca11c
3 files changed
+75 -29
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/appservices.mdx
+19 -11
View File
@@ -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 <name>`
where `<name>` 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.
docs/deploying/docker.mdx
+1 -1
View File
@@ -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:
docs/guides/dns.mdx
+55 -17
View File
@@ -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
</details>
:::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.
<details>
<summary>Example Docker deployment with an appservice</summary>
```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
```
~~~
</details>
:::
### 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 <SERVER_NAME>` and `!admin debug resolve-true-destination <SERVER_NAME>`.