mirror of
https://forgejo.ellis.link/continuwuation/continuwuity.git
synced 2025-07-28 02:38:30 +00:00
docs: Improve grammar in deployment documentation
This commit is contained in:
Jade Ellis
parent
3c320f6d6e
commit
2655acf269
6 changed files with 86 additions and 86 deletions
|
|
@ -1,5 +1,5 @@
|
|||
# Continuwuity for Arch Linux
|
||||
|
||||
Continuwuity is available on the `archlinuxcn` repository and AUR, with the same package name `continuwuity`, which includes latest taggged version. The development version is available on AUR as `continuwuity-git`
|
||||
Continuwuity is available in the `archlinuxcn` repository and AUR with the same package name `continuwuity`, which includes the latest tagged version. The development version is available on AUR as `continuwuity-git`.
|
||||
|
||||
Simply install the `continuwuity` package. Configure the service in `/etc/conduwuit/conduwuit.toml`, then enable/start the continuwuity.service.
|
||||
Simply install the `continuwuity` package. Configure the service in `/etc/conduwuit/conduwuit.toml`, then enable and start the continuwuity.service.
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## Docker
|
||||
|
||||
To run Continuwuity with Docker you can either build the image yourself or pull it
|
||||
To run Continuwuity with Docker, you can either build the image yourself or pull it
|
||||
from a registry.
|
||||
|
||||
### Use a registry
|
||||
|
|
@ -26,7 +26,7 @@ to pull it to your machine.
|
|||
|
||||
### Run
|
||||
|
||||
When you have the image you can simply run it with
|
||||
When you have the image, you can simply run it with
|
||||
|
||||
```bash
|
||||
docker run -d -p 8448:6167 \
|
||||
|
|
@ -36,7 +36,7 @@ docker run -d -p 8448:6167 \
|
|||
--name continuwuity $LINK
|
||||
```
|
||||
|
||||
or you can use [docker compose](#docker-compose).
|
||||
or you can use [Docker Compose](#docker-compose).
|
||||
|
||||
The `-d` flag lets the container run in detached mode. You may supply an
|
||||
optional `continuwuity.toml` config file, the example config can be found
|
||||
|
|
@ -46,15 +46,15 @@ using env vars. For an overview of possible values, please take a look at the
|
|||
[`docker-compose.yml`](docker-compose.yml) file.
|
||||
|
||||
If you just want to test Continuwuity for a short time, you can use the `--rm`
|
||||
flag, which will clean up everything related to your container after you stop
|
||||
flag, which cleans up everything related to your container after you stop
|
||||
it.
|
||||
|
||||
### Docker-compose
|
||||
|
||||
If the `docker run` command is not for you or your setup, you can also use one
|
||||
If the `docker run` command is not suitable for you or your setup, you can also use one
|
||||
of the provided `docker-compose` files.
|
||||
|
||||
Depending on your proxy setup, you can use one of the following files;
|
||||
Depending on your proxy setup, you can use one of the following files:
|
||||
|
||||
- If you already have a `traefik` instance set up, use
|
||||
[`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml)
|
||||
|
|
@ -65,7 +65,7 @@ Depending on your proxy setup, you can use one of the following files;
|
|||
`example.com` placeholders with your own domain
|
||||
- For any other reverse proxy, use [`docker-compose.yml`](docker-compose.yml)
|
||||
|
||||
When picking the traefik-related compose file, rename it so it matches
|
||||
When picking the Traefik-related compose file, rename it to
|
||||
`docker-compose.yml`, and rename the override file to
|
||||
`docker-compose.override.yml`. Edit the latter with the values you want for your
|
||||
server.
|
||||
|
|
@ -77,18 +77,18 @@ create the `caddy` network before spinning up the containers:
|
|||
docker network create caddy
|
||||
```
|
||||
|
||||
After that, you can rename it so it matches `docker-compose.yml` and spin up the
|
||||
After that, you can rename it to `docker-compose.yml` and spin up the
|
||||
containers!
|
||||
|
||||
Additional info about deploying Continuwuity can be found [here](generic.md).
|
||||
|
||||
### Build
|
||||
|
||||
Official Continuwuity images are built using **Docker Buildx** and the Dockerfile found at [`docker/Dockerfile`][dockerfile-path]. This approach uses common Docker tooling and enables multi-platform builds efficiently.
|
||||
Official Continuwuity images are built using **Docker Buildx** and the Dockerfile found at [`docker/Dockerfile`][dockerfile-path]. This approach uses common Docker tooling and enables efficient multi-platform builds.
|
||||
|
||||
The resulting images are broadly compatible with Docker and other container runtimes like Podman or containerd.
|
||||
The resulting images are widely compatible with Docker and other container runtimes like Podman or containerd.
|
||||
|
||||
The images *do not contain a shell*. They contain only the Continuwuity binary, required libraries, TLS certificates and metadata. Please refer to the [`docker/Dockerfile`][dockerfile-path] for the specific details of the image composition.
|
||||
The images *do not contain a shell*. They contain only the Continuwuity binary, required libraries, TLS certificates, and metadata. Please refer to the [`docker/Dockerfile`][dockerfile-path] for the specific details of the image composition.
|
||||
|
||||
To build an image locally using Docker Buildx, you can typically run a command like:
|
||||
|
||||
|
|
@ -109,8 +109,8 @@ Refer to the Docker Buildx documentation for more advanced build options.
|
|||
|
||||
### Run
|
||||
|
||||
If you already have built the image or want to use one from the registries, you
|
||||
can just start the container and everything else in the compose file in detached
|
||||
If you have already built the image or want to use one from the registries, you
|
||||
can start the container and everything else in the compose file in detached
|
||||
mode with:
|
||||
|
||||
```bash
|
||||
|
|
@ -121,20 +121,20 @@ docker compose up -d
|
|||
|
||||
### Use Traefik as Proxy
|
||||
|
||||
As a container user, you probably know about Traefik. It is a easy to use
|
||||
reverse proxy for making containerized app and services available through the
|
||||
As a container user, you probably know about Traefik. It is an easy-to-use
|
||||
reverse proxy for making containerized apps and services available through the
|
||||
web. With the two provided files,
|
||||
[`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml) (or
|
||||
[`docker-compose.with-traefik.yml`](docker-compose.with-traefik.yml)) and
|
||||
[`docker-compose.override.yml`](docker-compose.override.yml), it is equally easy
|
||||
to deploy and use Continuwuity, with a little caveat. If you already took a look at
|
||||
the files, then you should have seen the `well-known` service, and that is the
|
||||
little caveat. Traefik is simply a proxy and loadbalancer and is not able to
|
||||
serve any kind of content, but for Continuwuity to federate, we need to either
|
||||
expose ports `443` and `8448` or serve two endpoints `.well-known/matrix/client`
|
||||
to deploy and use Continuwuity, with a small caveat. If you have already looked at
|
||||
the files, you should have seen the `well-known` service, which is the
|
||||
small caveat. Traefik is simply a proxy and load balancer and cannot
|
||||
serve any kind of content. For Continuwuity to federate, we need to either
|
||||
expose ports `443` and `8448` or serve two endpoints: `.well-known/matrix/client`
|
||||
and `.well-known/matrix/server`.
|
||||
|
||||
With the service `well-known` we use a single `nginx` container that will serve
|
||||
With the service `well-known`, we use a single `nginx` container that serves
|
||||
those two files.
|
||||
|
||||
## Voice communication
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
# Continuwuity for FreeBSD
|
||||
|
||||
Continuwuity at the moment does not provide FreeBSD builds or have FreeBSD packaging, however Continuwuity does build and work on FreeBSD using the system-provided RocksDB.
|
||||
Continuwuity currently does not provide FreeBSD builds or FreeBSD packaging. However, Continuwuity does build and work on FreeBSD using the system-provided RocksDB.
|
||||
|
||||
Contributions for getting Continuwuity packaged are welcome.
|
||||
Contributions to get Continuwuity packaged for FreeBSD are welcome.
|
||||
|
|
|
|||
|
|
@ -13,31 +13,31 @@
|
|||
You may simply download the binary that fits your machine architecture (x86_64
|
||||
or aarch64). Run `uname -m` to see what you need.
|
||||
|
||||
Prebuilt fully static musl binaries can be downloaded from the latest tagged
|
||||
You can download prebuilt fully static musl binaries from the latest tagged
|
||||
release [here](https://forgejo.ellis.link/continuwuation/continuwuity/releases/latest) or
|
||||
`main` CI branch workflow artifact output. These also include Debian/Ubuntu
|
||||
from the `main` CI branch workflow artifact output. These also include Debian/Ubuntu
|
||||
packages.
|
||||
|
||||
These can be curl'd directly from. `ci-bins` are CI workflow binaries by commit
|
||||
You can download these directly using curl. The `ci-bins` are CI workflow binaries organized by commit
|
||||
hash/revision, and `releases` are tagged releases. Sort by descending last
|
||||
modified for the latest.
|
||||
modified date to find the latest.
|
||||
|
||||
These binaries have jemalloc and io_uring statically linked and included with
|
||||
them, so no additional dynamic dependencies need to be installed.
|
||||
|
||||
For the **best** performance; if using an `x86_64` CPU made in the last ~15 years,
|
||||
we recommend using the `-haswell-` optimised binaries. This sets
|
||||
`-march=haswell` which is the most compatible and highest performance with
|
||||
optimised binaries. The database backend, RocksDB, most benefits from this as it
|
||||
will then use hardware accelerated CRC32 hashing/checksumming which is critical
|
||||
For the **best** performance: if you are using an `x86_64` CPU made in the last ~15 years,
|
||||
we recommend using the `-haswell-` optimized binaries. These set
|
||||
`-march=haswell`, which provides the most compatible and highest performance with
|
||||
optimized binaries. The database backend, RocksDB, benefits most from this as it
|
||||
uses hardware-accelerated CRC32 hashing/checksumming, which is critical
|
||||
for performance.
|
||||
|
||||
### Compiling
|
||||
|
||||
Alternatively, you may compile the binary yourself. We recommend using
|
||||
Nix (or [Lix](https://lix.systems)) to build Continuwuity as this has the most
|
||||
guaranteed reproducibiltiy and easiest to get a build environment and output
|
||||
going. This also allows easy cross-compilation.
|
||||
Nix (or [Lix](https://lix.systems)) to build Continuwuity as this provides the most
|
||||
guaranteed reproducibility and makes it easiest to set up a build environment and generate
|
||||
output. This approach also allows for easy cross-compilation.
|
||||
|
||||
You can run the `nix build -L .#static-x86_64-linux-musl-all-features` or
|
||||
`nix build -L .#static-aarch64-linux-musl-all-features` commands based
|
||||
|
|
@ -53,9 +53,9 @@ You can build Continuwuity using `cargo build --release --all-features`
|
|||
|
||||
## Adding a Continuwuity user
|
||||
|
||||
While Continuwuity can run as any user it is better to use dedicated users for
|
||||
different services. This also allows you to make sure that the file permissions
|
||||
are correctly set up.
|
||||
While Continuwuity can run as any user, it is better to use dedicated users for
|
||||
different services. This also ensures that the file permissions
|
||||
are set up correctly.
|
||||
|
||||
In Debian, you can use this command to create a Continuwuity user:
|
||||
|
||||
|
|
@ -71,18 +71,18 @@ 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 port 8448, and clients must be using port 443.
|
||||
If you would like to use only port 443, or a different port, you will need to setup
|
||||
delegation. Continuwuity has config options for doing delegation, or you can configure
|
||||
your reverse proxy to manually serve the necessary JSON files to do delegation
|
||||
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 these public ports need to be forwarded directly
|
||||
or indirectly to the port mentioned in the config.
|
||||
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 the inside
|
||||
of your network, you need to research your router and see if it supports "NAT
|
||||
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
|
||||
|
|
@ -92,19 +92,19 @@ on the network level, consider something like NextDNS or Pi-Hole.
|
|||
|
||||
## Setting up a systemd service
|
||||
|
||||
Two example systemd units for Continuwuity can be found
|
||||
You can find two example systemd units for Continuwuity
|
||||
[on the configuration page](../configuration/examples.md#debian-systemd-unit-file).
|
||||
You may need to change the `ExecStart=` path to where you placed the Continuwuity
|
||||
binary if it is not `/usr/bin/conduwuit`.
|
||||
You may need to change the `ExecStart=` path to match where you placed the Continuwuity
|
||||
binary if it is not in `/usr/bin/conduwuit`.
|
||||
|
||||
On systems where rsyslog is used alongside journald (i.e. Red Hat-based distros
|
||||
and OpenSUSE), put `$EscapeControlCharactersOnReceive off` inside
|
||||
`/etc/rsyslog.conf` to allow color in logs.
|
||||
|
||||
If you are using a different `database_path` other than the systemd unit
|
||||
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
|
||||
systemd unit's `ReadWritePaths=`. This can be done by either directly editing
|
||||
`conduwuit.service` and reloading systemd, or running `systemctl edit conduwuit.service`
|
||||
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:
|
||||
|
||||
```
|
||||
|
|
@ -114,8 +114,8 @@ ReadWritePaths=/path/to/custom/database/path
|
|||
|
||||
## Creating the Continuwuity configuration file
|
||||
|
||||
Now we need to create the Continuwuity's config file in
|
||||
`/etc/continuwuity/continuwuity.toml`. The example config can be found at
|
||||
Now you need to create the Continuwuity configuration file in
|
||||
`/etc/continuwuity/continuwuity.toml`. You can find an example configuration at
|
||||
[conduwuit-example.toml](../configuration/examples.md).
|
||||
|
||||
**Please take a moment to read the config. You need to change at least the
|
||||
|
|
@ -125,8 +125,8 @@ RocksDB is the only supported database backend.
|
|||
|
||||
## Setting the correct file permissions
|
||||
|
||||
If you are using a dedicated user for Continuwuity, you will need to allow it to
|
||||
read the config. To do that you can run this:
|
||||
If you are using a dedicated user for Continuwuity, you need to allow it to
|
||||
read the configuration. To do this, run:
|
||||
|
||||
```bash
|
||||
sudo chown -R root:root /etc/conduwuit
|
||||
|
|
@ -143,13 +143,13 @@ sudo chmod 700 /var/lib/conduwuit/
|
|||
|
||||
## Setting up the Reverse Proxy
|
||||
|
||||
We recommend Caddy as a reverse proxy, as it is trivial to use, handling TLS certificates, reverse proxy headers, etc transparently with proper defaults.
|
||||
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.
|
||||
|
||||
### Caddy
|
||||
|
||||
After installing Caddy via your preferred method, create `/etc/caddy/conf.d/conduwuit_caddyfile`
|
||||
and enter this (substitute for your server name).
|
||||
and enter the following (substitute your actual server name):
|
||||
|
||||
```caddyfile
|
||||
your.server.name, your.server.name:8448 {
|
||||
|
|
@ -168,9 +168,9 @@ sudo systemctl enable --now caddy
|
|||
|
||||
### Other Reverse Proxies
|
||||
|
||||
As we would prefer our users to use Caddy, we will not provide configuration files for other proxys.
|
||||
As we prefer our users to use Caddy, we do not provide configuration files for other proxies.
|
||||
|
||||
You will need to reverse proxy everything under following routes:
|
||||
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`
|
||||
|
|
@ -193,16 +193,16 @@ Examples of delegation:
|
|||
|
||||
For Apache and Nginx there are many examples available online.
|
||||
|
||||
Lighttpd is not supported as it seems to mess with the `X-Matrix` Authorization
|
||||
header, making federation non-functional. If a workaround is found, feel free to share to get it added to the documentation here.
|
||||
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 messing with the `X-Matrix` header (note that Apache isn't very good as a general reverse proxy and we discourage the usage of it if you can).
|
||||
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 give Continuwuity the request URI using `$request_uri`, or like so:
|
||||
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;`
|
||||
|
||||
Nginx users need to increase `client_max_body_size` (default is 1M) to match
|
||||
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
|
||||
|
|
@ -222,7 +222,7 @@ sudo systemctl enable conduwuit
|
|||
## How do I know it works?
|
||||
|
||||
You can open [a Matrix client](https://matrix.org/ecosystem/clients), enter your
|
||||
homeserver and try to register.
|
||||
homeserver address, and try to register.
|
||||
|
||||
You can also use these commands as a quick health check (replace
|
||||
`your.server.name`).
|
||||
|
|
@ -237,10 +237,10 @@ curl https://your.server.name:8448/_conduwuit/server_version
|
|||
curl https://your.server.name:8448/_matrix/federation/v1/version
|
||||
```
|
||||
|
||||
- To check if your server can talk with other homeservers, you can use the
|
||||
- To check if your server can communicate with other homeservers, use the
|
||||
[Matrix Federation Tester](https://federationtester.matrix.org/). If you can
|
||||
register but cannot join federated rooms check your config again and also check
|
||||
if the port 8448 is open and forwarded correctly.
|
||||
register but cannot join federated rooms, check your configuration and verify
|
||||
that port 8448 is open and forwarded correctly.
|
||||
|
||||
# What's next?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
# Continuwuity for Kubernetes
|
||||
|
||||
Continuwuity doesn't support horizontal scalability or distributed loading
|
||||
natively, however a community maintained Helm Chart is available here to run
|
||||
conduwuit on Kubernetes: <https://gitlab.cronce.io/charts/conduwuit>
|
||||
natively. However, a community-maintained Helm Chart is available here to run
|
||||
Continuwuity on Kubernetes: <https://gitlab.cronce.io/charts/conduwuit>
|
||||
|
||||
This should be compatible with continuwuity, but you will need to change the image reference.
|
||||
This should be compatible with Continuwuity, but you will need to change the image reference.
|
||||
|
||||
Should changes need to be made, please reach out to the maintainer as this is not maintained/controlled by the Continuwuity maintainers.
|
||||
If changes need to be made, please reach out to the maintainer, as this is not maintained or controlled by the Continuwuity maintainers.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Continuwuity for NixOS
|
||||
|
||||
Continuwuity can be acquired by Nix (or [Lix][lix]) from various places:
|
||||
You can acquire Continuwuity with Nix (or [Lix][lix]) from various places:
|
||||
|
||||
* The `flake.nix` at the root of the repo
|
||||
* The `default.nix` at the root of the repo
|
||||
|
|
@ -9,25 +9,25 @@ Continuwuity can be acquired by Nix (or [Lix][lix]) from various places:
|
|||
### NixOS module
|
||||
|
||||
The `flake.nix` and `default.nix` do not currently provide a NixOS module (contributions
|
||||
welcome!), so [`services.matrix-conduit`][module] from Nixpkgs can be used to configure
|
||||
welcome!), so you can use [`services.matrix-conduit`][module] from Nixpkgs to configure
|
||||
Continuwuity.
|
||||
|
||||
### Conduit NixOS Config Module and SQLite
|
||||
|
||||
Beware! The [`services.matrix-conduit`][module] module defaults to SQLite as a database backend.
|
||||
Continuwuity dropped SQLite support in favor of exclusively supporting the much faster RocksDB.
|
||||
Make sure that you are using the RocksDB backend before migrating!
|
||||
Make sure you are using the RocksDB backend before migrating!
|
||||
|
||||
There is a [tool to migrate a Conduit SQLite database to
|
||||
RocksDB](https://github.com/ShadowJonathan/conduit_toolbox/).
|
||||
|
||||
If you want to run the latest code, you should get Continuwuity from the `flake.nix`
|
||||
If you want to run the latest code, get Continuwuity from the `flake.nix`
|
||||
or `default.nix` and set [`services.matrix-conduit.package`][package]
|
||||
appropriately to use Continuwuity instead of Conduit.
|
||||
|
||||
### UNIX sockets
|
||||
|
||||
Due to the lack of a Continuwuity NixOS module, when using the `services.matrix-conduit` module
|
||||
Due to the lack of a Continuwuity NixOS module, when using the `services.matrix-conduit` module,
|
||||
a workaround like the one below is necessary to use UNIX sockets. This is because the UNIX
|
||||
socket option does not exist in Conduit, and the module forcibly sets the `address` and
|
||||
`port` config options.
|
||||
|
|
@ -44,21 +44,21 @@ options.services.matrix-conduit.settings = lib.mkOption {
|
|||
```
|
||||
|
||||
Additionally, the [`matrix-conduit` systemd unit][systemd-unit] in the module does not allow
|
||||
the `AF_UNIX` socket address family in their systemd unit's `RestrictAddressFamilies=` which
|
||||
disallows the namespace from accessing or creating UNIX sockets and has to be enabled like so:
|
||||
the `AF_UNIX` socket address family in its systemd unit's `RestrictAddressFamilies=`. This
|
||||
disallows the namespace from accessing or creating UNIX sockets and must be enabled like this:
|
||||
|
||||
```nix
|
||||
systemd.services.conduit.serviceConfig.RestrictAddressFamilies = [ "AF_UNIX" ];
|
||||
```
|
||||
|
||||
Even though those workarounds are feasible a Continuwuity NixOS configuration module, developed and
|
||||
Although these workarounds are feasible, a dedicated Continuwuity NixOS configuration module, developed and
|
||||
published by the community, would be appreciated.
|
||||
|
||||
### jemalloc and hardened profile
|
||||
|
||||
Continuwuity uses jemalloc by default. This may interfere with the [`hardened.nix` profile][hardened.nix]
|
||||
due to them using `scudo` by default. You must either disable/hide `scudo` from Continuwuity, or
|
||||
disable jemalloc like so:
|
||||
because it uses `scudo` by default. You must either disable/hide `scudo` from Continuwuity or
|
||||
disable jemalloc like this:
|
||||
|
||||
```nix
|
||||
let
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue