update some documentation a bit for new users

Signed-off-by: strawberry <strawberry@puppygock.gay>
This commit is contained in:
strawberry 2024-04-25 20:21:48 -04:00 committed by June
parent 5195593f55
commit 6fd3123660
7 changed files with 64 additions and 65 deletions

4
Cargo.lock generated
View file

@ -2108,9 +2108,9 @@ checksum = "b15813163c1d831bf4a13c3610c05c0d03b39feb07f7e09fa234dac9b15aaf39"
[[package]] [[package]]
name = "parking_lot" name = "parking_lot"
version = "0.12.1" version = "0.12.2"
source = "registry+https://github.com/rust-lang/crates.io-index" source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3742b2c103b9f06bc9fff0a37ff4912935851bee6d36f3c02bcc755bcfec228f" checksum = "7e4af0ca4f6caed20e900d564c242b8e5d4903fdacf31d3daf527b66fe6f42fb"
dependencies = [ dependencies = [
"lock_api", "lock_api",
"parking_lot_core", "parking_lot_core",

View file

@ -306,7 +306,7 @@ features = ["bundled"]
# used only by rusqlite # used only by rusqlite
[dependencies.parking_lot] [dependencies.parking_lot]
version = "0.12.1" version = "0.12.2"
optional = true optional = true
# used only by rusqlite # used only by rusqlite

View file

@ -32,7 +32,6 @@ services:
CONDUIT_ALLOW_FEDERATION: 'true' CONDUIT_ALLOW_FEDERATION: 'true'
CONDUIT_ALLOW_CHECK_FOR_UPDATES: 'true' CONDUIT_ALLOW_CHECK_FOR_UPDATES: 'true'
CONDUIT_TRUSTED_SERVERS: '["matrix.org"]' CONDUIT_TRUSTED_SERVERS: '["matrix.org"]'
#CONDUIT_MAX_CONCURRENT_REQUESTS: 100
#CONDUIT_LOG: warn,state_res=warn #CONDUIT_LOG: warn,state_res=warn
CONDUIT_ADDRESS: 0.0.0.0 CONDUIT_ADDRESS: 0.0.0.0
#CONDUIT_CONFIG: './conduwuit.toml' # Uncomment if you mapped config toml above #CONDUIT_CONFIG: './conduwuit.toml' # Uncomment if you mapped config toml above

View file

@ -32,7 +32,6 @@ services:
CONDUIT_ALLOW_FEDERATION: 'true' CONDUIT_ALLOW_FEDERATION: 'true'
CONDUIT_ALLOW_CHECK_FOR_UPDATES: 'true' CONDUIT_ALLOW_CHECK_FOR_UPDATES: 'true'
CONDUIT_TRUSTED_SERVERS: '["matrix.org"]' CONDUIT_TRUSTED_SERVERS: '["matrix.org"]'
#CONDUIT_MAX_CONCURRENT_REQUESTS: 400
#CONDUIT_LOG: warn,state_res=warn #CONDUIT_LOG: warn,state_res=warn
CONDUIT_ADDRESS: 0.0.0.0 CONDUIT_ADDRESS: 0.0.0.0
#CONDUIT_CONFIG: './conduwuit.toml' # Uncomment if you mapped config toml above #CONDUIT_CONFIG: './conduwuit.toml' # Uncomment if you mapped config toml above

View file

@ -1,4 +1,4 @@
# Conduwuit for Docker # conduwuit for Docker
## Docker ## Docker
@ -11,19 +11,22 @@ OCI images for conduwuit are available in the registries listed below.
| Registry | Image | Size | Notes | | Registry | Image | Size | Notes |
| --------------- | --------------------------------------------------------------- | ----------------------------- | ---------------------- | | --------------- | --------------------------------------------------------------- | ----------------------------- | ---------------------- |
| GitHub Registry | [ghcr.io/girlbossceo/conduwuit:latest][gh] | ![Image Size][shield-latest] | Stable image. | | GitHub Registry | [ghcr.io/girlbossceo/conduwuit:latest][gh] | ![Image Size][shield-latest] | Stable tagged image. |
| Docker Hub | [docker.io/girlbossceo/conduwuit:latest][dh] | ![Image Size][shield-latest] | Stable image. | | Docker Hub | [docker.io/girlbossceo/conduwuit:latest][dh] | ![Image Size][shield-latest] | Stable tagged image. |
| GitHub Registry | [ghcr.io/girlbossceo/conduwuit:main][gh] | ![Image Size][shield-main] | Development version. | | GitHub Registry | [ghcr.io/girlbossceo/conduwuit:main][gh] | ![Image Size][shield-main] | Stable branch. |
| Docker Hub | [docker.io/girlbossceo/conduwuit:main][dh] | ![Image Size][shield-main] | Development version. | | Docker Hub | [docker.io/girlbossceo/conduwuit:main][dh] | ![Image Size][shield-main] | Stable branch. |
| GitHub Registry | [ghcr.io/girlbossceo/conduwuit:dev][gh] | ![Image Size][shield-main] | Development version. |
| Docker Hub | [docker.io/girlbossceo/conduwuit:dev][dh] | ![Image Size][shield-dev] | Development version. |
[dh]: https://hub.docker.com/repository/docker/girlbossceo/conduwuit [dh]: https://hub.docker.com/repository/docker/girlbossceo/conduwuit
[gh]: https://github.com/girlbossceo/conduwuit/pkgs/container/conduwuit [gh]: https://github.com/girlbossceo/conduwuit/pkgs/container/conduwuit
[shield-latest]: https://img.shields.io/docker/image-size/girlbossceo/conduwuit/latest [shield-latest]: https://img.shields.io/docker/image-size/girlbossceo/conduwuit/latest
[shield-main]: https://img.shields.io/docker/image-size/girlbossceo/conduwuit/main [shield-main]: https://img.shields.io/docker/image-size/girlbossceo/conduwuit/main
[shield-dev]: https://img.shields.io/docker/image-size/girlbossceo/conduwuit/dev
Use Use
```bash ```bash
docker image pull <link> docker image pull <link>
``` ```
@ -33,7 +36,7 @@ to pull it to your machine.
### Build using a Dockerfile ### Build using a Dockerfile
The Dockerfile provided by Conduit has two stages, each of which creates an image. The Dockerfile provided by conduwuit has two stages, each of which creates an image.
1. **Builder:** Builds the binary from local context or by cloning a git revision from the official repository. 1. **Builder:** Builds the binary from local context or by cloning a git revision from the official repository.
2. **Runner:** Copies the built binary from **Builder** and sets up the runtime environment, like creating a volume to persist the database and applying the correct permissions. 2. **Runner:** Copies the built binary from **Builder** and sets up the runtime environment, like creating a volume to persist the database and applying the correct permissions.
@ -54,25 +57,24 @@ When you have the image you can simply run it with
```bash ```bash
docker run -d -p 8448:6167 \ docker run -d -p 8448:6167 \
-v db:/var/lib/matrix-conduit/ \ -v db:/var/lib/conduwuit/ \
-e CONDUIT_SERVER_NAME="your.server.name" \ -e CONDUIT_SERVER_NAME="your.server.name" \
-e CONDUIT_DATABASE_BACKEND="rocksdb" \ -e CONDUIT_DATABASE_BACKEND="rocksdb" \
-e CONDUIT_ALLOW_REGISTRATION=true \ -e CONDUIT_ALLOW_REGISTRATION=false \
-e CONDUIT_ALLOW_FEDERATION=true \ -e CONDUIT_ALLOW_FEDERATION=true \
-e CONDUIT_MAX_REQUEST_SIZE="20000000" \ -e CONDUIT_MAX_REQUEST_SIZE="40000000" \
-e CONDUIT_TRUSTED_SERVERS="[\"matrix.org\"]" \ -e CONDUIT_TRUSTED_SERVERS="[\"matrix.org\"]" \
-e CONDUIT_MAX_CONCURRENT_REQUESTS="500" \
-e CONDUIT_LOG="warn,ruma_state_res=warn" \ -e CONDUIT_LOG="warn,ruma_state_res=warn" \
--name conduit <link> --name conduit <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 now need to supply a `conduit.toml` config file, an example can be found [here](../configuration.md). The `-d` flag lets the container run in detached mode. You now need to supply a `conduwuit.toml` config file, an example can be found [here](../configuration.md).
You can pass in different env vars to change config values on the fly. You can even configure Conduit completely by using env vars, but for that you need You can pass in different env vars to change config values on the fly. You can even configure conduwuit completely by using env vars, but for that you need
to pass `-e CONDUIT_CONFIG=""` into your container. For an overview of possible values, please take a look at the `docker-compose.yml` file. to pass `-e CONDUIT_CONFIG=""` into your container. For an overview of possible values, please take a look at the `docker-compose.yml` file.
If you just want to test Conduit for a short time, you can use the `--rm` flag, which will clean up everything related to your container after you stop it. If you just want to test conduwuit for a short time, you can use the `--rm` flag, which will clean up everything related to your container after you stop it.
### Docker-compose ### Docker-compose
@ -87,14 +89,14 @@ When picking the traefik-related compose file, rename it so it matches `docker-c
rename the override file to `docker-compose.override.yml`. Edit the latter with the values you want rename the override file to `docker-compose.override.yml`. Edit the latter with the values you want
for your server. for your server.
Additional info about deploying Conduit can be found [here](generic.md). Additional info about deploying conduwuit can be found [here](generic.md).
### Build ### Build
To build the Conduit image with docker-compose, you first need to open and modify the `docker-compose.yml` file. There you need to comment the `image:` option and uncomment the `build:` option. Then call docker compose with: To build the conduwuit image with docker-compose, you first need to open and modify the `docker-compose.yml` file. There you need to comment the `image:` option and uncomment the `build:` option. Then call docker compose with:
```bash ```bash
docker-compose up docker compose up
``` ```
This will also start the container right afterwards, so if want it to run in detached mode, you also should use the `-d` flag. This will also start the container right afterwards, so if want it to run in detached mode, you also should use the `-d` flag.
@ -104,7 +106,7 @@ This will also start the container right afterwards, so if want it to run in det
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 mode with: 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 mode with:
```bash ```bash
docker-compose up -d docker compose up -d
``` ```
> **Note:** Don't forget to modify and adjust the compose file to your needs. > **Note:** Don't forget to modify and adjust the compose file to your needs.
@ -116,9 +118,9 @@ containerized app and services available through the web. With the two provided
[`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml) (or [`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml) (or
[`docker-compose.with-traefik.yml`](docker-compose.with-traefik.yml)) and [`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 [`docker-compose.override.yml`](docker-compose.override.yml), it is equally easy to deploy
and use Conduit, with a little caveat. If you already took a look at the files, then you should have and use conduwuit, 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 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 Conduit to federate, we need to loadbalancer and is not able to serve any kind of content, but for conduwuit to federate, we need to
either expose ports `443` and `8448` or serve two endpoints `.well-known/matrix/client` and either expose ports `443` and `8448` or serve two endpoints `.well-known/matrix/client` and
`.well-known/matrix/server`. `.well-known/matrix/server`.
@ -129,7 +131,7 @@ So...step by step:
1. Copy [`docker-compose.for-traefik.yml`](docker-compose.for-traefik.yml) (or 1. Copy [`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) from the repository and remove `.for-traefik` (or `.with-traefik`) from the filename. [`docker-compose.with-traefik.yml`](docker-compose.with-traefik.yml)) and [`docker-compose.override.yml`](docker-compose.override.yml) from the repository and remove `.for-traefik` (or `.with-traefik`) from the filename.
2. Open both files and modify/adjust them to your needs. Meaning, change the `CONDUIT_SERVER_NAME` and the volume host mappings according to your needs. 2. Open both files and modify/adjust them to your needs. Meaning, change the `CONDUIT_SERVER_NAME` and the volume host mappings according to your needs.
3. Create the `conduit.toml` config file, an example can be found [here](../configuration.md), or set `CONDUIT_CONFIG=""` and configure Conduit per env vars. 3. Create the `conduwuit.toml` config file, an example can be found [here](../configuration.md), or set `CONDUIT_CONFIG=""` and configure conduwuit per env vars.
4. Uncomment the `element-web` service if you want to host your own Element Web Client and create a `element_config.json`. 4. Uncomment the `element-web` service if you want to host your own Element Web Client and create a `element_config.json`.
5. Create the files needed by the `well-known` service. 5. Create the files needed by the `well-known` service.
@ -157,7 +159,7 @@ So...step by step:
} }
``` ```
6. Run `docker-compose up -d` 6. Run `docker compose up -d`
7. Connect to your homeserver with your preferred client and create a user. You should do this immediately after starting Conduit, because the first created user is the admin. 7. Connect to your homeserver with your preferred client and create a user. You should do this immediately after starting Conduit, because the first created user is the admin.
@ -165,7 +167,7 @@ So...step by step:
## Voice communication ## Voice communication
In order to make or receive calls, a TURN server is required. Conduit suggests using [Coturn](https://github.com/coturn/coturn) for this purpose, which is also available as a Docker image. Before proceeding with the software installation, it is essential to have the necessary configurations in place. In order to make or receive calls, a TURN server is required. conduwuit suggests using [Coturn](https://github.com/coturn/coturn) for this purpose, which is also available as a Docker image. Before proceeding with the software installation, it is essential to have the necessary configurations in place.
### Configuration ### Configuration
@ -178,7 +180,7 @@ realm=<your server domain>
``` ```
A common way to generate a suitable alphanumeric secret key is by using `pwgen -s 64 1`. A common way to generate a suitable alphanumeric secret key is by using `pwgen -s 64 1`.
These same values need to be set in conduit. You can either modify conduit.toml to include these lines: These same values need to be set in conduwuit. You can either modify conduwuit.toml to include these lines:
``` ```
turn_uris = ["turn:<your server domain>?transport=udp", "turn:<your server domain>?transport=tcp"] turn_uris = ["turn:<your server domain>?transport=udp", "turn:<your server domain>?transport=tcp"]
turn_secret = "<secret key from coturn configuration>" turn_secret = "<secret key from coturn configuration>"
@ -191,13 +193,13 @@ CONDUIT_TURN_SECRET: "<secret key from coturn configuration>"
Restart Conduit to apply these changes. Restart Conduit to apply these changes.
### Run ### Run
Run the [Coturn](https://hub.docker.com/r/coturn/coturn) image using Run the [Coturn](https://hub.docker.com/r/coturn/coturn) image using
```bash ```bash
docker run -d --network=host -v $(pwd)/coturn.conf:/etc/coturn/turnserver.conf coturn/coturn docker run -d --network=host -v $(pwd)/coturn.conf:/etc/coturn/turnserver.conf coturn/coturn
``` ```
or docker-compose. For the latter, paste the following section into a file called `docker-compose.yml` or docker-compose. For the latter, paste the following section into a file called `docker-compose.yml`
and run `docker-compose up -d` in the same directory. and run `docker compose up -d` in the same directory.
```yml ```yml
version: 3 version: 3
@ -213,4 +215,3 @@ services:
To understand why the host networking mode is used and explore alternative configuration options, please visit the following link: https://github.com/coturn/coturn/blob/master/docker/coturn/README.md. To understand why the host networking mode is used and explore alternative configuration options, please visit the following link: https://github.com/coturn/coturn/blob/master/docker/coturn/README.md.
For security recommendations see Synapse's [Coturn documentation](https://github.com/matrix-org/synapse/blob/develop/docs/setup/turn/coturn.md#configuration). For security recommendations see Synapse's [Coturn documentation](https://github.com/matrix-org/synapse/blob/develop/docs/setup/turn/coturn.md#configuration).

View file

@ -22,47 +22,47 @@ $ sudo apt install libclang-dev build-essential
# RHEL # RHEL
$ sudo dnf install clang $ sudo dnf install clang
``` ```
Then, `cd` into the source tree of conduit-next and run: Then, `cd` into the source tree of conduwuit and run:
```bash ```bash
$ cargo build --release $ cargo build --release
``` ```
## Adding a Conduit user ## Adding a conduwuit user
While Conduit can run as any user it is usually better to use dedicated users for different services. This also allows While conduwuit can run as any user it is usually better to use dedicated users for different services. This also allows
you to make sure that the file permissions are correctly set up. you to make sure that the file permissions are correctly set up.
In Debian or RHEL, you can use this command to create a Conduit user: In Debian or RHEL, you can use this command to create a conduwuit user:
```bash ```bash
sudo adduser --system conduit --group --disabled-login --no-create-home sudo adduser --system conduwuit --group --disabled-login --no-create-home
``` ```
## Forwarding ports in the firewall or the router ## Forwarding ports in the firewall or the router
Conduit uses the ports 443 and 8448 both of which need to be open in the firewall. conduwuit uses the ports 443 and 8448 both of which need to be open in the firewall.
If Conduit 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. If conduwuit 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.
## Setting up a systemd service ## Setting up a systemd service
Now we'll set up a systemd service for Conduit, so it's easy to start/stop Conduit and set it to autostart when your Now we'll set up a systemd service for conduwuit, so it's easy to start/stop conduwuit and set it to autostart when your
server reboots. Simply paste the default systemd service you can find below into server reboots. Simply paste the default systemd service you can find below into
`/etc/systemd/system/conduit.service`. `/etc/systemd/system/conduwuit.service`.
```systemd ```systemd
[Unit] [Unit]
Description=Conduwuit Matrix Server Description=conduwuit Matrix Server
After=network.target After=network.target
[Service] [Service]
Environment="CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml" Environment="CONDUWUIT_CONFIG=/etc/conduwuit/conduwuit.toml"
User=conduit User=conduwuit
Group=conduit Group=conduwuit
RuntimeDirectory=conduit RuntimeDirectory=conduwuit
RuntimeDirectoryMode=0750 RuntimeDirectoryMode=0750
Restart=always Restart=always
ExecStart=/usr/local/bin/matrix-conduit ExecStart=/usr/local/bin/conduwuit
[Install] [Install]
WantedBy=multi-user.target WantedBy=multi-user.target
@ -74,30 +74,30 @@ Finally, run
$ sudo systemctl daemon-reload $ sudo systemctl daemon-reload
``` ```
## Creating the Conduit configuration file ## Creating the conduwuit configuration file
Now we need to create the Conduit's config file in `/etc/conduwuit/conduwuit.toml`. Paste this in **and take a moment Now we need to create the conduwuit's config file in `/etc/conduwuit/conduwuit.toml`. Paste this in **and take a moment
to read it. You need to change at least the server name.** to read it. You need to change at least the server name.**
RocksDB (`rocksdb`) is the only supported database backend. SQLite only exists for historical reasons and is not recommended. Any performance issues, storage issues, database issues, etc will not be assisted if using SQLite and you will be asked to migrate to RocksDB first. RocksDB (`rocksdb`) is the only supported database backend. SQLite only exists for historical reasons and is not recommended. Any performance issues, storage issues, database issues, etc will not be assisted if using SQLite and you will be asked to migrate to RocksDB first.
See the following example config at [conduwuit-example.toml](../configuration.md) See the following example config at [conduwuit-example.toml](../configuration.md)
## Setting the correct file permissions ## Setting the correct file permissions
As we are using a Conduit specific user we need to allow it to read the config. To do that you can run this command on As we are using a conduwuit specific user we need to allow it to read the config. To do that you can run this command on
Debian or RHEL: Debian or RHEL:
```bash ```bash
sudo chown -R root:root /etc/matrix-conduit sudo chown -R root:root /etc/conduwuit
sudo chmod 755 /etc/matrix-conduit sudo chmod 755 /etc/conduwuit
``` ```
If you use the default database path you also need to run this: If you use the default database path you also need to run this:
```bash ```bash
sudo mkdir -p /var/lib/matrix-conduit/ sudo mkdir -p /var/lib/conduwuit/
sudo chown -R conduit:conduit /var/lib/matrix-conduit/ sudo chown -R conduwuit:conduwuit /var/lib/conduwuit/
sudo chmod 700 /var/lib/matrix-conduit/ sudo chmod 700 /var/lib/conduwuit/
``` ```
## Setting up the Reverse Proxy ## Setting up the Reverse Proxy
@ -114,7 +114,7 @@ your.server.name, your.server.name:8448 {
reverse_proxy 127.0.0.1:6167 reverse_proxy 127.0.0.1:6167
# UNIX socket # UNIX socket
#reverse_proxy unix//run/conduit/conduit.sock #reverse_proxy unix//run/conduwuit/conduwuit.sock
} }
``` ```
@ -126,16 +126,16 @@ $ sudo systemctl enable caddy
## You're done! ## You're done!
Now you can start Conduit with: Now you can start conduwuit with:
```bash ```bash
$ sudo systemctl start conduit $ sudo systemctl start conduwuit
``` ```
Set it to start automatically when your system boots with: Set it to start automatically when your system boots with:
```bash ```bash
$ sudo systemctl enable conduit $ sudo systemctl enable conduwuit
``` ```
## How do I know it works? ## How do I know it works?

View file

@ -1,10 +1,10 @@
# Conduwuit for NixOS # conduwuit for NixOS
Conduwuit can be acquired by Nix from various places: conduwuit can be acquired by Nix from various places:
* The `flake.nix` at the root of the repo * The `flake.nix` at the root of the repo
* The `default.nix` at the root of the repo * The `default.nix` at the root of the repo
* From Conduwuit's binary cache * From conduwuit's binary cache
A binary cache for conduwuit that the CI/CD publishes to is available at the A binary cache for conduwuit that the CI/CD publishes to is available at the
following places (both are the same just different names): following places (both are the same just different names):
@ -20,7 +20,7 @@ If specifying a URL in your flake, please use the GitHub remote: `github:girlbos
The `flake.nix` and `default.nix` do not (currently) provide a NixOS module, so The `flake.nix` and `default.nix` do not (currently) provide a NixOS module, so
(for now) [`services.matrix-conduit`][module] from Nixpkgs should be used to (for now) [`services.matrix-conduit`][module] from Nixpkgs should be used to
configure Conduit. configure conduwuit.
If you want to run the latest code, you should get Conduwuit from the `flake.nix` If you want to run the latest code, you should get Conduwuit from the `flake.nix`
or `default.nix` and set [`services.matrix-conduit.package`][package] or `default.nix` and set [`services.matrix-conduit.package`][package]