serv/conduit
1
0
Fork 0
mirror of https://gitlab.com/famedly/conduit.git synced 2025-01-15 14:06:26 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

WIP: change layout of config options documentation

Browse source
This commit is contained in:
Jonas Zohren 2021-09-07 11:36:28 +02:00
parent d0e06b49da
commit afa71756c0
1 changed files with 136 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

148
docs/configuration/configuration.md
View file

@ -11,22 +11,146 @@ configure Conduit with just environment variables.
Mandatory variables must be configured in order for Conduit to run properly. Mandatory variables must be configured in order for Conduit to run properly.
| Key in Conduit.toml | Environment variable | Default value | Description | ### Server Name
|---------------------|-------------------------|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server_name` | `CONDUIT_SERVER_NAME` | | The server_name is the name of this server. It is used as a suffix for user and room ids. Examples: matrix.org, conduit.rs. The Conduit server needs to be reachable at https://your.server.name/ on port 443 (client-server) and 8448 (server-server) OR you can create /.well-known files to redirect requests. See [Client-Server specs](https://matrix.org/docs/spec/client_server/latest#get-well-known-matrix-client) and [Server-Server specs](https://matrix.org/docs/spec/server_server/r0.1.4#get-well-known-matrix-server) for more information. | - Config file key: `server_name`
| `database_path` | `CONDUIT_DATABASE_PATH` | `/var/lib/conduit/` | A directory Conduit where Conduit stores its database and media files. This directory must exist and be writable before Conduit is started. | - Envirnoment variable: `CONDUIT_SERVER_NAME`
| `port` | `CONDUIT_PORT` | `6167` | The port Conduit will be running on. You need to set up a reverse proxy in your web server (e.g. apache or nginx), so all requests to /_matrix on port 443 and 8448 will be forwarded to the Conduit instance running on this port. | - Default value: _None, you will need to choose your own._
The server_name is the name of this server. It is used as a suffix for user and room ids.
Example: If you set it to `conduit.rs`, your usernames will look like `@somebody:conduit.rs`.
The Conduit server needs to be reachable at https://your.server.name/ on port 443 (client-server) and 8448 (server-server) OR you can create /.well-known files to redirect requests.
See the [Client-Server specs](https://matrix.org/docs/spec/client_server/latest#get-well-known-matrix-client) and the [Server-Server specs](https://matrix.org/docs/spec/server_server/r0.1.4#get-well-known-matrix-server) for more information.
### Database Path
- Config file key: `database_path`
- Envirnoment variable: `CONDUIT_DATABASE_PATH`
- Default value: _None, but many people like to use `/var/lib/conduit/`_.
A directory where Conduit stores its database and media files.
This directory must exist, have enough free space and be readable and writable by the user Conduit is running as.
What does _enough free space_ mean? It heavily on the amount of messages your Conduit server will see and the
amount and size of media files users on your Conduit server send.
As a rule of thumb, you should have at least 10 GB of free space left.
You should be comfortable for quite some time with 50 GB.
### TCP Port
- Config file key: `port`
- Environment variable: `CONDUIT_PORT`
- Default value: _None, but many people like to use `6167`_.
The TCP port Conduit will listen on for connections. The port needs to be free (no other program is listeing on it).
Conduit does currently (2021-09) not offer HTTPS by itself. Only unencrypted HTTP requests will be accepted on this port.
Unless you know what you are doing, this port should not be exposed to the internet.
Instead, use a reverse proxy capable of doing TLS to offer your Conduit server to the internet via HTTPS.
See [TODO] for example configurations.
## Optional configuration options
These config options come with defaults and don't need to be configured for Conduit to run.
That said, you should still check them to make sure that your Conduit server behaves like you want it to do.
### Maximum request size
- Config file key: `max_request_size`
- Environment variable: `CONDUIT_MAX_REQUEST_SIZE`
- Default value: `20_000_000` (~= 20 MB)
The maximum size in bytes for incoming requests to Conduit. You can use underscores to improve readability.
This will effectively limit the size for images, videos and other files users on your Conduit server can send.
### Allow Registration?
- Config file key: `allow_registration`
- Environment variable: `CONDUIT_ALLOW_REGISTRATION`
- Default value: `true`
- Possible values: `true`, `false`
It this is set to `false`, no new users can register accounts on your Conduit server.
Already registered users will not be affected from this setting and can continue to user your server.
The first user to ever register on your Conduit server will be considered the admin account and
is automatically invited into the admin room.
### Allow Encryption?
- Config file key: `allow_encryption`
- Environment variable: `CONDUIT_ALLOW_ENCRYPTION`
- Default value: `true`
- Possible values: `true`, `false`
If this is set to `false`, Conduit disables the ability for users to create encrypted chats.
Existing encrypted chats may continue to work.
### Allow federation?
- Config file key: `allow_federation`
- Environment variable: `CONDUIT_ALLOW_FEDERATION`
- Default value: `false`
- Possible values: `true`, `false`
Federation means that users from different Matrix servers can chat with each other.
E.g. `@mathew:matrix.org` can chat with `@timo:conduit.rs`.
If this option is set to `false`, users on your Conduit server can only talk with other users on your Conduit server.
Federation with other servers needs to happen over HTTPS, so make sure you have set up a reverse proxy.
### Jaeger Tracing
- Config file key: `allow_jaeger`
- Environment variable: `CONDUIT_ALLOW_JAEGER`
- Default value: `false`
- Possible values: `true`, `false`
Enable Jaeger to support monitoring and troubleshooting through Jaeger.
If you don't know what Jaeger is, you can safely leave this set to `false`.
### Trusted servers
- Config file key: `trusted_servers`
- Environment variable: `CONDUIT_TRUSTED_SERVERS`
- Default value: `[]`
- Possible values: JSON-Array of server domains, e.g. `["matrix.org"]` or `["matrix.org", "conduit.rs"]`.
Matrix servers have so-called "server keys", which authenticate messages from their users.
Because your Conduit server might not know the server keys from every server it encounters,
it can ask a _trusted server_ for them.
This speeds things up for rooms with people from a lot of different servers.
You should only set this to include trustworthy servers.
Most people consider a good default to be `["matrix.org"]`.
Only relevant if you have federation enabled.
### Maximum request size
- Config file key: ``
- Environment variable: ``
- Default value: ``
- Possible values: `true`, `false`
## Optional config options
| Key in Conduit.toml | Environment variable | Default value | Description | | Key in Conduit.toml | Environment variable | Default value | Description |
|---------------------------|-----------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |---------------------------|-----------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_request_size` | `CONDUIT_MAX_REQUEST_SIZE` | `20_000_000` | The maximum size in bytes for uploads (files sent from users on this Conduit server). Uploads will be stored in the database path, so make sure that it has sufficient free space. |
| `allow_registration` | `CONDUIT_ALLOW_REGISTRATION` | `true` | Are new users allowed to register accounts on their own? Possible values: `true`, `false`. |
| `allow_encryption` | `CONDUIT_ALLOW_ENCRYPTION` | `true` | Controls whether encrypted rooms can be created or not. Possible values: `true`, `false`. |
| `allow_federation` | `CONDUIT_ALLOW_FEDERATION` | `false` | Federation enables users on your Conduit server to talk to other Matrix users on different Matrix servers. If federation is turned off, only users on your Conduit server can talk to each other. Possible values: `true`, `false`. |
| `allow_jaeger` | `CONDUIT_ALLOW_JAEGER` | `false` | Enable jaeger to support monitoring and troubleshooting through jaeger. Possible values: `true`, `false`. |
| `trusted_servers` | `CONDUIT_TRUSTED_SERVERS` | `[]` | List of servers, which Conduit trusts enough to ask them for public keys of other, newly found servers. E.g. to trust the matrix.org server, set this value to `["matrix.org"]`. |
| `max_concurrent_requests` | `CONDUIT_MAX_CONCURRENT_REQUESTS` | `100` | How many requests Conduit sends to other servers at the same time. | | `max_concurrent_requests` | `CONDUIT_MAX_CONCURRENT_REQUESTS` | `100` | How many requests Conduit sends to other servers at the same time. |
| `log` | `CONDUIT_LOG` | `info,state_res=warn,rocket=off,_=off,sled=off` | Configures which kind of messages Conduit logs. | | `log` | `CONDUIT_LOG` | `info,state_res=warn,rocket=off,_=off,sled=off` | Configures which kind of messages Conduit logs. |
| `workers` | `CONDUIT_WORKERS` | cpu core count * 2 | How many worker processes are used. | | `workers` | `CONDUIT_WORKERS` | cpu core count * 2 | How many worker processes are used. |