From c79f2a3057d1df4487cd43841c21ca9cd6ea66d4 Mon Sep 17 00:00:00 2001 From: stratself Date: Thu, 16 Apr 2026 17:11:16 +0000 Subject: [PATCH] docs(generic): Fix router + reverse proxy + docker build sections * Link docker builds to section in dev pages * Delete old section on port forwarding * Create new section on port exposing, near reverse proxy section * Rewrite Other Reverse Proxies section to update specified routes * Move reverse proxy software caveats into its own subsection * Other wording and structure fixes and improvements --- docs/deploying/generic.mdx | 93 ++++++++++++++------------------------ 1 file changed, 35 insertions(+), 58 deletions(-) diff --git a/docs/deploying/generic.mdx b/docs/deploying/generic.mdx index 8fa85fdba..18cffddf2 100644 --- a/docs/deploying/generic.mdx +++ b/docs/deploying/generic.mdx @@ -61,7 +61,8 @@ ### Compiling #### Using Docker -If you would like to build using docker, you can run the command `docker build -f ./docker/Dockerfile -t forgejo.ellis.link/continuwuation/continuwuity:main .` to compile continuwuity. +See the [Building Docker Images](../development/index.mdx#building-docker-images) +section in the development documentation. #### Manual @@ -107,27 +108,6 @@ ## Adding a Continuwuity user sudo useradd -r --shell /usr/bin/nologin --no-create-home continuwuity ``` -## Forwarding ports in the firewall or the router - -Matrix's default federation port is 8448, and clients must use port 443. -If you would like to use only port 443 or a different port, you will need to set up -delegation. Continuwuity has configuration options for delegation, or you can configure -your reverse proxy to manually serve the necessary JSON files for delegation -(see the `[global.well_known]` config section). - -If Continuwuity runs behind a router or in a container and has a different public -IP address than the host system, you need to forward these public ports directly -or indirectly to the port mentioned in the configuration. - -Note for NAT users: if you have trouble connecting to your server from inside -your network, check if your router supports "NAT -hairpinning" or "NAT loopback". - -If your router does not support this feature, you need to research doing local -DNS overrides and force your Matrix DNS records to use your local IP internally. -This can be done at the host level using `/etc/hosts`. If you need this to be -on the network level, consider something like NextDNS or Pi-Hole. - ## Setting up a systemd service You can find an example unit for continuwuity below. @@ -139,7 +119,7 @@ ## Setting up a systemd service `/etc/rsyslog.conf` to allow color in logs. If you are using a different `database_path` than the systemd unit's -configured default `/var/lib/conduwuit`, you need to add your path to the +configured default (`/var/lib/conduwuit`), you need to add your path to the systemd unit's `ReadWritePaths=`. You can do this by either directly editing `conduwuit.service` and reloading systemd, or by running `systemctl edit conduwuit.service` and entering the following: @@ -173,9 +153,7 @@ ## Creating the Continuwuity configuration file **Please take a moment to read the config. You need to change at least the server name.** -RocksDB is the only supported database backend. - -## Setting the correct file permissions +### Setting the correct file permissions If you are using a dedicated user for Continuwuity, you need to allow it to read the configuration. To do this, run: @@ -193,22 +171,29 @@ ## Setting the correct file permissions sudo chmod 700 /var/lib/conduwuit/ ``` -## Setting up the Reverse Proxy +## Exposing ports in the firewall or the router -We recommend Caddy as a reverse proxy because it is trivial to use and handles TLS certificates, reverse proxy headers, etc. transparently with proper defaults. -For other software, please refer to their respective documentation or online guides. +Matrix's default federation port is **:8448**, and clients use port **:443**. You will need to +expose these ports on your firewall or router. If you use UFW, the commands to allow them +are: `ufw allow 8448/tcp` and `ufw allow 443/tcp`. + +:::tip Alternative port/domain setups +If you would like to use only port 443, a different port, or a subdomain for the homeserver, you will need to set up `.well-known` delegation. Consult the `[global.well_known]` section of the config file, and the [**Delegation/Split-domain**](../advanced/delegation) page to learn more about these kinds of deployments. +::: + +## Setting up the Reverse Proxy ### Caddy -After installing Caddy via your preferred method, create `/etc/caddy/conf.d/conduwuit_caddyfile` -and enter the following (substitute your actual server name): +Caddy is the recommended reverse proxy as it is easy to use, has good defaults, and handle TLS +certificates automatically. After installing Caddy via your preferred method, create +`/etc/caddy/conf.d/conduwuit_caddyfile` and enter the following (substitute `example.com` +with your actual server name): ``` example.com, example.com:8448 { # TCP reverse_proxy - reverse_proxy 127.0.0.1:6167 - # UNIX socket - #reverse_proxy unix//run/conduwuit/conduwuit.sock + reverse_proxy 127.0.0.1:8008 } ``` @@ -222,9 +207,13 @@ ### Other Reverse Proxies You will need to reverse proxy everything under the following routes: -- `/_matrix/` - core Matrix C-S and S-S APIs -- `/_conduwuit/` and/or `/_continuwuity/` - ad-hoc Continuwuity routes such as `/local_user_count` and - `/server_version` +- `/_matrix/` - core Matrix APIs, which includes: + + - `/_matrix/federation` and `/_matrix/key` - core Server-Server APIs. These should be available on port :8448 + + - `/_matrix/client` - core Client-Server APIs. These should be available on port :443 + +- `/_conduwuit/` and/or `/_continuwuity/` - ad-hoc Continuwuity routes such as `/local_user_count` and `/server_version` You can optionally reverse proxy the following individual routes: @@ -232,35 +221,23 @@ ### Other Reverse Proxies Continuwuity to perform delegation (see the `[global.well_known]` config section) - `/.well-known/matrix/support` if using Continuwuity to send the homeserver admin contact and support page (formerly known as MSC1929) -- `/` if you would like to see `hewwo from conduwuit woof!` at the root +- `/` and `/_continuwuity/logo.svg` if you would like to see the Continuwuity landing page -See the following spec pages for more details on these files: +Normally, all of these could be achieved by reverse proxying everything from port :8448 and :443 back to Continuwuity. Refer to the respective software's documentation and online guides on how to do so. -- [`/.well-known/matrix/server`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixserver) -- [`/.well-known/matrix/client`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient) -- [`/.well-known/matrix/support`](https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixsupport) +#### Caveats for specific reverse proxies -Examples of delegation: - -- https://continuwuity.org/.well-known/matrix/server -- https://continuwuity.org/.well-known/matrix/client -- https://ellis.link/.well-known/matrix/server -- https://ellis.link/.well-known/matrix/client - -For Apache and Nginx there are many examples available online. - -Lighttpd is not supported as it appears to interfere with the `X-Matrix` Authorization +- Lighttpd is not supported as it appears to interfere with the `X-Matrix` Authorization header, making federation non-functional. If you find a workaround, please share it so we can add it to this documentation. -If using Apache, you need to use `nocanon` in your `ProxyPass` directive to prevent httpd from interfering with the `X-Matrix` header (note that Apache is not ideal as a general reverse proxy, so we discourage using it if alternatives are available). +- If using Apache, you need to use `nocanon` in your `ProxyPass` directive to prevent httpd from interfering with the `X-Matrix` header (note that Apache is not ideal as a general reverse proxy, so we discourage using it if alternatives are available). -If using Nginx, you need to pass the request URI to Continuwuity using `$request_uri`, like this: +- If using Nginx, you need to pass the request URI to Continuwuity using `$request_uri`, like this: -- `proxy_pass http://127.0.0.1:6167$request_uri;` -- `proxy_pass http://127.0.0.1:6167;` + - `proxy_pass http://127.0.0.1:6167$request_uri;` + - `proxy_pass http://127.0.0.1:6167;` -Nginx users need to increase the `client_max_body_size` setting (default is 1M) to match the -`max_request_size` defined in conduwuit.toml. + Nginx users need to increase the `client_max_body_size` setting (default is 1M) to match the `max_request_size` defined in conduwuit.toml. ## You're done