@@ -55,3 +93,3 @@
 ### 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.

@@ -74,11 +112,11 @@ Some values that are commonly tuned include:
 
 - 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.

@@ -130,6 +143,6 @@ management.
 Built-in S3 support is also planned, but for now using a "S3 filesystem" on

@@ -131,3 +143,1 @@
-`media/` works. Continuwuity also sends a `Cache-Control` header of 1 year and
-immutable for all media requests (download and thumbnail) to reduce unnecessary
-media requests from browsers, reduce bandwidth usage, and reduce load.
+While Continuwuity does not implement built-in S3 support, using an "S3 filesystem

@@ -54,0 +58,4 @@
+
+### 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#for-docker-users) to connect to your appservice via static IPs.

@@ -65,3 +64,3 @@
 
 :::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.

@@ -90,0 +90,4 @@
+Create a Caddyfile with the following content:
+
+```
+https://example.com:443, https://example.com:8448 {

@@ -187,6 +197,21 @@ Test that your setup works by following these [instructions](./generic.mdx#how-d
 
 Check your container logs using `docker-compose logs --follow` to debug any issues. See the [Troubleshooting](../troubleshooting.mdx) page for common errors and how to fix them.
 
+## Updating

@@ -55,3 +55,3 @@
 - `/.well-known/matrix/client`: for Client-Server discovery
 - `/.well-known/matrix/server`: for Server-Server (federation) discovery
-- `/.well-known/matrix/support`: admin contact details (strongly recommended to have)
+- `/.well-known/matrix/support`: admin contact details (strongly recommended to have). By default, this include members of the admin room.

@@ -129,2 +133,2 @@
-:::warning
-Even if you choose to serve the well-known files manually, if you are using delegation at all, you **must** still set the `global.well_known.client` configuration option to the domain you're delegating to. Continuwuity needs to know the domain it runs on for OAuth-compatible clients to work correctly.
+:::warning Warning: always configure [global.well_known]
+Even if you choose to serve the well-known files manually, you **must** still set the `global.well_known.client` configuration option to the domain you're delegating to. Continuwuity needs to know the domain it runs on, in order to redirect clients properly to email, OAuth, and account management endpoints.

@@ -196,0 +200,4 @@
+
+- [Federation Setup guide by MTRNord](https://connectivity-tester.mtrnord.blog/docs/getting-started/federation-setup)
+
+See the following Matrix Specs for full details on client/server resolution mechanisms:

@@ -196,0 +202,4 @@
+
+See the following Matrix Specs for full details on client/server resolution mechanisms:
+
+- [Server-to-Server resolution](https://spec.matrix.org/latest/server-server-api/#resolving-server-names) (see this for more information on SRV records)

@@ -196,0 +210,4 @@
+
+### Docker Compose examples
+
+The following Compose files are taken from [Docker instructions](../deploying/docker.mdx) and reconfigured to support split-domain delegation. Note the updated `CONTINUWUITY_WELL_KNOWN` variable and relevant changes in reverse proxy rules.

@@ -196,0 +220,4 @@
+```
+
+```txt title="Caddyfile"
+https://matrix.example.com:443 {

@@ -197,3 +262,2 @@
 :::warning
-The following methods are **not recommended** due to increased complexity with little benefits. If you have already set up `.well-known` delegation as above, you can safely skip this part.
-:::
+The following methods use DNS SRV records, and are **not recommended** due to increased complexity with little benefits. They also work with federation traffic only.

@@ -200,2 +263,3 @@
+The following methods use DNS SRV records, and are **not recommended** due to increased complexity with little benefits. They also work with federation traffic only.
 
-The following methods uses SRV DNS records and only work with federation traffic. They are only included for completeness.
+If you have already set up `.well-known` delegation as above, you can safely skip this part.

@@ -19,3 +19,3 @@
 ### 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.

@@ -29,2 +29,3 @@
 networks:
-  matrix_net:
+
+  # re-use the `proxy` network, as shown in Docker deployment docs,

@@ -54,1 +60,4 @@
 
+:::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.

@@ -55,3 +93,3 @@
 ### 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 Continuwuity's configuration, in order to only resolve for IPv4 and remove unnecessary AAAA queries.

@@ -78,2 +115,3 @@
+### 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.

@@ -145,3 +183,3 @@
 ## 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.

@@ -7,3 +7,3 @@
 ## DNS tuning (recommended)
 
-Please see the dedicated [DNS tuning guide](./dns.mdx).
+For federating servers, DNS tuning is important for a smooth experience. Please see the dedicated [DNS tuning guide](./dns.mdx).

@@ -46,4 +47,4 @@
 
 ### Compression
 
 Some RocksDB settings can be adjusted such as the compression method chosen. See

@@ -43,3 +43,3 @@
 via liburing for improved read performance.
 
-RocksDB troubleshooting can be found [in the RocksDB section of troubleshooting](troubleshooting.md).
+RocksDB troubleshooting can be found [in the RocksDB section of

@@ -50,1 +51,3 @@
-the RocksDB section in the [example config](./reference/config.mdx).
+the RocksDB section in the [example config](./reference/config.mdx), and the
+[database compression section](./guides/performance.mdx#tuning-database-compression)
+in the perf-tuning documentation for more.

@@ -85,1 +88,3 @@
-same. This is unfortunately a bad design choice by Facebook as we are using the
+### Database online backup
+
+If you'd like to backup your database online without any downtime, see the

@@ -86,0 +91,4 @@
+[`!admin server` command](./reference/admin/server.md) for the backup commands
+and the `database_backup_path` config options in the example config.
+
+Please note that the format of the database backup is not the exact same.

@@ -132,2 +143,2 @@
-immutable for all media requests (download and thumbnail) to reduce unnecessary
-media requests from browsers, reduce bandwidth usage, and reduce load.
+While Continuwuity does not implement built-in S3 support, using an "S3 filesystem
+on the `media/` path will works. Continuwuity also sends a `Cache-Control` header

@@ -133,1 +143,3 @@
-media requests from browsers, reduce bandwidth usage, and reduce load.
+While Continuwuity does not implement built-in S3 support, using an "S3 filesystem
+on the `media/` path will works. Continuwuity also sends a `Cache-Control` header
+of 1 year and immutable for all media requests (download and thumbnail)

@@ -1,3 +1,8 @@
+## Configuration file reference
+
+This configuration file reflect latest developments on the `main` branch. To check the file from a specific Continuwuity version, browse the [tags](https://forgejo.ellis.link/continuwuation/continuwuity/tags) and view the `conduwuit-example.toml` file there.

@@ -61,1 +61,3 @@
-## Reverse proxying well-known files to Continuwuity
+## Serving well-known files
+
+You can either reverse proxy well-known paths to Continuwuity, or serve static JSON files yourself.

@@ -30,1 +30,3 @@
-  matrix_net:
+
+  # re-use the `proxy` network, as shown in Docker deployment docs,
+  # with a custom subnet

@@ -28,3 +28,3 @@
 ```yaml title="docker-compose.yml"
 networks:
-  matrix_net:
+

@@ -194,2 +200,3 @@
+## Related Documentation
 
-## Using SRV records (not recommended)
+Community guides:

@@ -196,0 +203,4 @@
+
+- [Federation Setup guide by MTRNord](https://connectivity-tester.mtrnord.blog/docs/getting-started/federation-setup)
+
+See the following sections of the Matrix Specification for more details on client and server resolution mechanisms:

@@ -54,1 +59,4 @@
 
+:::warning Breaking resolution with container hostnames
+
+After you mount a custom `/etc/resolv.conf`, you won't be able to connect to other container using their hostnames, such as for [appservices](../appservices.mdx) in the same Docker network. To work around this, force your appservice to use a static IP address, and refer to its static IP during registration.