diff --git a/docs/appservices.mdx b/docs/appservices.mdx index d6717a821..7a7ed2b48 100644 --- a/docs/appservices.mdx +++ b/docs/appservices.mdx @@ -58,4 +58,4 @@ where `` one of the output of `appservices list`. ### 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. +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 using their hostnames. Follow the [workaround in the guide](./guides/dns.mdx#for-docker-users) to connect to your appservice using static IPs. diff --git a/docs/deploying/docker.mdx b/docs/deploying/docker.mdx index bbc19ddd5..c95e64151 100644 --- a/docs/deploying/docker.mdx +++ b/docs/deploying/docker.mdx @@ -62,7 +62,7 @@ See the [reference configuration](../reference/config) page for all config optio 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 +:::important 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, we will mount a custom `/etc/resolv.conf` config file into the Continuwuity container. ```yaml title='docker-compose.yml' diff --git a/docs/guides/delegation.mdx b/docs/guides/delegation.mdx index 338f9e560..3d85d2b69 100644 --- a/docs/guides/delegation.mdx +++ b/docs/guides/delegation.mdx @@ -53,14 +53,17 @@ services: After doing the steps above, Continuwuity will serve these 3 JSON files: - `/.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). By default, this include members of the admin room. + +- `/.well-known/matrix/support`: admin contact details (strongly recommended). + - By default, this include members of the admin room. To enable full discovery, you will need to reverse proxy these paths from the base domain back to Continuwuity. ## Serving well-known files -You can either reverse proxy well-known paths to Continuwuity, or serve static JSON files yourself. +You can either reverse proxy the well-known paths to Continuwuity, or serve static JSON files yourself. ### Option 1: Reverse proxying well-known files to Continuwuity @@ -130,8 +133,8 @@ After applying these changes, restart Continuwuity and your reverse proxy. Visit Instead of reverse proxying well-known URIs, you can serve these files directly as static JSON that match the ones above. This is useful if your base domain points to a different physical server, and reverse proxying isn't feasible. -:::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. +:::important Important: 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. :::
@@ -200,9 +203,9 @@ Community guides: - [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: +See the following sections of the Matrix Specification for more details on client and 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) +- [Server-to-Server resolution](https://spec.matrix.org/latest/server-server-api/#resolving-server-names) - [Client-to-Server resolution](https://spec.matrix.org/latest/client-server-api/#server-discovery) - [MSC1929: Homeserver Admin Contact and Support page](https://github.com/matrix-org/matrix-spec-proposals/pull/1929) @@ -210,7 +213,7 @@ See the following Matrix Specs for full details on client/server resolution mech ### 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. +The following Compose files are taken from [Docker deployment 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.
Caddy (using Caddyfile) - delegated.docker-compose.with-caddy.yml ([view raw](/advanced/delegated.docker-compose.with-caddy.yml)) @@ -260,9 +263,9 @@ https://example.com:443 { ### Using SRV records (not recommended) :::warning -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 use DNS SRV records, and are **not recommended** due to increased complexity with few benefits. Additionally, they only work for federation traffic. -If you have already set up `.well-known` delegation as above, you can safely skip this part. +If you have already set up well-known delegation as above, you can safely skip this part. :::
@@ -306,7 +309,7 @@ On the target's IP at port 443, you'll need to provide a valid route and cert fo
-Using SRV records as a fallback for .well-known delegation +Using SRV records as a fallback for well-known delegation Assume your delegation is as below: diff --git a/docs/guides/dns.mdx b/docs/guides/dns.mdx index 9a7a8f7e3..4a5ae45be 100644 --- a/docs/guides/dns.mdx +++ b/docs/guides/dns.mdx @@ -18,7 +18,7 @@ nameserver 127.0.0.1 ### For Docker users -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. +By default, Docker bridge networks uses a poorly performing 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,10 +27,9 @@ It is recommended to run a dedicated resolver container for Continuwuity, as to ```yaml title="docker-compose.yml" networks: - - # re-use the `proxy` network, as shown in Docker deployment docs, - # with a custom subnet - # https://continuwuity.org/deploying/docker#choose-your-reverse-proxy + # re-use the `proxy` network, as shown in the Docker deployment docs + # (https://continuwuity.org/deploying/docker#choose-your-reverse-proxy) + # and configure it with a custom subnet proxy: ipam: driver: default @@ -60,7 +59,7 @@ nameserver 10.10.10.20 :::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. +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.
Example Docker deployment with an appservice @@ -92,7 +91,7 @@ url: http://10.10.10.30:29318 ### For IPv4-only users -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. +If you don't have IPv6 connectivity, change `ip_lookup_strategy` to `1` in Continuwuity's configuration in order to onlyresolve IPv4 addresses and remove unnecessary IPv6 queries. ```toml title="continuwuity.toml" [global] @@ -114,7 +113,7 @@ Some values that are commonly tuned include: ### Using a forwarder (optional) -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. +Unbound employs **recursive resolution** by default, contacting many nameservers around the world in the process. 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 caches. 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. @@ -182,7 +181,7 @@ You may consult this [community guide][technitium-continuwuity] for more details ## Testing -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. +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 issue, 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 `. diff --git a/docs/guides/performance.mdx b/docs/guides/performance.mdx index e1f293dcf..08ecf7ac0 100644 --- a/docs/guides/performance.mdx +++ b/docs/guides/performance.mdx @@ -6,7 +6,7 @@ This page aims to outline various performance tweaks for Continuwuity and their ## DNS tuning (recommended) -For federating servers, DNS tuning is important for a smooth experience. Please see the dedicated [DNS tuning guide](./dns.mdx). +DNS tuning is important to ensure a smooth experience for federated servers. Please see the dedicated [DNS tuning guide](./dns.mdx). ## Cache capacities diff --git a/docs/maintenance.mdx b/docs/maintenance.mdx index 411ca145b..362e92d2b 100644 --- a/docs/maintenance.mdx +++ b/docs/maintenance.mdx @@ -42,15 +42,14 @@ running compaction is not recommended, or compaction via a timer, due to creating unnecessary I/O amplification. RocksDB is built with io_uring support via liburing for improved read performance. -RocksDB troubleshooting can be found [in the RocksDB section of -troubleshooting](./troubleshooting.mdx#rocksdb--database-issues). +RocksDB troubleshooting can be found [in the RocksDB section of troubleshooting](./troubleshooting.mdx#rocksdb--database-issues). ### Compression -Some RocksDB settings can be adjusted such as the compression method chosen. See -the RocksDB section in the [example config](./reference/config.mdx), and the +Some RocksDB settings can be adjusted, such as the chosen compression method and level. +See 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. +in the performance tuning documentation for more. #### Caveats for btrfs users @@ -87,14 +86,15 @@ config option. ### Database online backup -If you'd like to backup your database online without any downtime, see the -[`!admin server` command](./reference/admin/server.md) for the backup commands -and the `database_backup_path` config options in the example config. +f you'd like to run an online backup of your database - that is, a backup with +no downtime - check the [`!admin server` command](./reference/admin/server.md) +for the required 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. -This is unfortunately a bad design choice by Facebook as we are using the -database backup engine API from RocksDB, however the data is still there and can -still be joined together. +Please note that the format of the database backup is not the exact same as the +format of offline backups. This is unfortunately a bad design choice by Facebook +as we are using the database backup engine API from RocksDB, however the data +is still there and can still be joined together. To restore a backup from an online RocksDB backup: @@ -140,9 +140,9 @@ the file created time (`btime`) or file modified time (`mtime`) See the [`!admin media` commands](./reference/admin/media.md) for further information. All media in Continuwuity is stored at `$DATABASE_DIR/media`. -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) -to reduce unnecessary bandwidth and load. +While Continuwuity does not implement built-in S3 support, using an S3 filesystem +mount on the `media/` path will work. Continuwuity also sends a `Cache-Control` +header of 1 year with the `immutable` directive for all media requests +(download and thumbnail) to reduce unnecessary bandwidth and load. [rocksdb-compaction]: https://github.com/facebook/rocksdb/wiki/Compaction diff --git a/docs/reference/config.mdx b/docs/reference/config.mdx index a240b40a2..5258e4867 100644 --- a/docs/reference/config.mdx +++ b/docs/reference/config.mdx @@ -1,6 +1,6 @@ ## 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. +This configuration file reflect the latest developments on the `main` branch. To check the configuration from a specific Continuwuity version, browse the [tags](https://forgejo.ellis.link/continuwuation/continuwuity/tags) and navigate to the `conduwuit-example.toml` file for that version. ---