Skip to content

Commit 03ebc20

Browse files
tcpipuktcpipuk
committed
Conduwuit
Sections added on deploying Conduwuit using Docker with either Caddy or Nginx, mainly covering the common Docker options and linking back to the official docs.
1 parent 8699f11 commit 03ebc20

File tree

8 files changed

+718
-0
lines changed

8 files changed

+718
-0
lines changed

Diff for: ‎src/SUMMARY.md

+7
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
# Table of Contents
22

33
- [Welcome](welcome.md)
4+
- [Matrix Conduwuit](conduwuit/README.md)
5+
- [Docker Deployment](conduwuit/docker.md)
6+
- [Configuration](conduwuit/config.md)
7+
- [Reverse Proxies](conduwuit/reverse-proxies/README.md)
8+
- [SSL Certificates](conduwuit/reverse-proxies/ssl.md)
9+
- [Caddy Configuration](conduwuit/reverse-proxies/caddy.md)
10+
- [Nginx Configuration](conduwuit/reverse-proxies/nginx.md)
411
- [Matrix Synapse](synapse/README.md)
512
- [Deployment](synapse/deployment/README.md)
613
- [Docker Compose with Templates](synapse/deployment/docker.md)

Diff for: ‎src/conduwuit/README.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Matrix Conduwuit Homeserver Guides
2+
3+
This section provides comprehensive guides for deploying Conduwuit, a featureful fork of the Conduit
4+
Matrix homeserver. Written in Rust, Conduwuit aims to be a high-performance and efficient homeserver
5+
that's easy to set up and "just works".
6+
7+
## Quick Start
8+
9+
These Docker guides will walk you through:
10+
11+
1. [Docker Deployment](docker.md) - Set up the Conduwuit container
12+
2. [Server Configuration](config.md) - Configure your homeserver
13+
3. [Reverse Proxies](reverse-proxies/README.md) - Set up external access
14+
- [SSL Certificates](reverse-proxies/ssl.md) - Secure your server
15+
- Choose your proxy:
16+
- [Caddy](reverse-proxies/caddy.md) - Simple, automatic HTTPS
17+
- [Nginx](reverse-proxies/nginx.md) - Popular and flexible
18+
19+
## Deployment Options
20+
21+
While these guides focus on Docker deployment, Conduwuit provides several installation options:
22+
23+
- **Docker containers** (covered in this guide)
24+
- **Debian packages** (.deb) for x86_64 and ARM64
25+
- **Static binaries** for Linux (x86_64/ARM64) and macOS (x86_64/ARM64)
26+
27+
You can find all these options in the [official releases](https://github.com/girlbossceo/conduwuit/releases).
28+
For non-Docker deployments, refer to the [generic deployment guide](https://conduwuit.puppyirl.gay/deploying/generic.html)
29+
which covers setting up users, systemd services, and more.
30+
31+
Conduwuit is quite stable and very usable as a daily driver for low-medium sized homeservers. While
32+
technically in Beta (inherited from Conduit), this status is becoming less relevant as the codebase
33+
significantly diverges from upstream Conduit.
34+
35+
Key features and differences from Conduit:
36+
37+
- Written in Rust for high performance and memory efficiency
38+
- Complete drop-in replacement for Conduit (when using RocksDB)
39+
- Single-process architecture (no worker configuration needed)
40+
- Actively maintained with regular updates
41+
- Designed for stability and real-world use
42+
43+
## Getting Help
44+
45+
If you need assistance, you can join these Matrix rooms:
46+
47+
- [#conduwuit:puppygock.gay](https://matrix.to/#/#conduwuit:puppygock.gay) -
48+
Main support and discussion
49+
- [#conduwuit-offtopic:girlboss.ceo](https://matrix.to/#/#conduwuit-offtopic:girlboss.ceo) -
50+
Community chat
51+
- [#conduwuit-dev:puppygock.gay](https://matrix.to/#/#conduwuit-dev:puppygock.gay) -
52+
Development discussion
53+
54+
Please review our [Community Code of Conduct](https://conduwuit.puppyirl.gay/conduwuit_coc.html)
55+
before participating in these rooms.
56+
57+
## Try It Out
58+
59+
You can try Conduwuit on the official instance at `transfem.dev`, which provides both
60+
[Element](https://element.transfem.dev) and [Cinny](https://cinny.transfem.dev) web clients.
61+
This is a public homeserver listed on [servers.joinmatrix.org](https://servers.joinmatrix.org),
62+
so please review the rules at [transfem.dev/homeserver_rules.txt](https://transfem.dev/homeserver_rules.txt)
63+
before registering.
64+
65+
Let's get started with deploying your own efficient Matrix homeserver!

Diff for: ‎src/conduwuit/config.md

+120
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Configuring Conduwuit
2+
3+
This guide covers the essential Conduwuit configuration options for Docker deployments. For a
4+
complete reference, see the [example configuration file](https://github.com/girlbossceo/conduwuit/blob/main/conduwuit-example.toml).
5+
6+
## Example Configuration
7+
8+
Start by downloading the example configuration file which includes comprehensive documentation for
9+
all available options:
10+
11+
```bash
12+
curl -o data/conduwuit.toml https://raw.githubusercontent.com/girlbossceo/conduwuit/main/conduwuit-example.toml
13+
```
14+
15+
## Core Settings
16+
17+
These are the only required settings:
18+
19+
```toml:conduwuit.toml
20+
[global]
21+
# Your server's domain name (required)
22+
server_name = "server.name"
23+
24+
# Trusted servers for key verification (recommended)
25+
trusted_servers = ["envs.net", "beeper.com", "matrix.org"]
26+
```
27+
28+
## Connection Settings
29+
30+
Choose between TCP ports or Unix sockets:
31+
32+
```toml:conduwuit.toml
33+
# TCP Configuration
34+
port = 6167
35+
address = "0.0.0.0" # For Docker
36+
37+
# Or Unix Socket Configuration (recommended when possible)
38+
unix_socket_path = "/run/conduwuit/conduwuit.sock"
39+
unix_socket_perms = 666
40+
```
41+
42+
**Note:** If you're using Unix sockets, you'll need to ensure the `port` and `address` settings are
43+
commented out or you'll get an error when Conduwuit launches.
44+
45+
## Federation and Security
46+
47+
```toml:conduwuit.toml
48+
# Federation Controls
49+
allow_federation = true
50+
allow_public_room_directory_over_federation = true
51+
allow_profile_lookup_federation_requests = true
52+
53+
# Registration Controls
54+
allow_registration = true
55+
registration_token = "your-secure-token-here"
56+
57+
# Privacy Settings
58+
allow_device_name_federation = false
59+
allow_legacy_media = false # Enable to allow older clients and servers to load media
60+
```
61+
62+
You can generate a secure registration token using this command:
63+
64+
```bash
65+
# Generate a 64-character random token
66+
openssl rand -base64 48 | tr -d '/+' | cut -c1-64
67+
```
68+
69+
## Performance Tuning
70+
71+
In practice, I've found requiring DNS over TCP is the best way to run Conduwuit, as it can easily
72+
DNS resolvers with UDP, and TCP offers a higher level of reliability.
73+
74+
If you want to do this, you can set the cache high to save repeated lookups, and increase the
75+
timeout to allow the batched lookups over TCP to do their thing:
76+
77+
```toml:conduwuit.toml
78+
# DNS Optimisation
79+
dns_cache_entries = 1_000_000
80+
dns_timeout = 60
81+
query_over_tcp_only = true
82+
```
83+
84+
## Presence and Real-time Features
85+
86+
Conduwuit is extremely performant over federation, so these options should perform very well, but
87+
you can choose whether or not you want them for performance or privacy reasons:
88+
89+
```toml:conduwuit.toml
90+
# Presence Settings
91+
allow_local_presence = true
92+
allow_incoming_presence = true
93+
allow_outgoing_presence = true
94+
95+
# Typing Indicators
96+
allow_outgoing_typing = true
97+
allow_incoming_typing = true
98+
```
99+
100+
## URL Preview Settings
101+
102+
URL previews are a great way to improve the user experience of your Matrix server, but they can
103+
also be a source of abuse, so you can choose whether you want to use them here:
104+
105+
```toml:conduwuit.toml
106+
# URL Preview Controls
107+
url_preview_domain_contains_allowlist = ["*"]
108+
url_preview_domain_explicit_allowlist = ["*"]
109+
url_preview_url_contains_allowlist = ["*"]
110+
url_preview_max_spider_size = 16_777_216
111+
url_preview_check_root_domain = true
112+
```
113+
114+
## Advanced Options
115+
116+
There are tons of other options available, including setting TURN servers for VoIP calling.
117+
118+
For detailed tuning of database performance, federation behaviour, or other advanced settings,
119+
refer to the [example configuration file](https://raw.githubusercontent.com/girlbossceo/conduwuit/main/conduwuit-example.toml)
120+
which includes comprehensive documentation for all available options.

Diff for: ‎src/conduwuit/docker.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Deploying Conduwuit with Docker
2+
3+
This guide covers deploying Conduwuit using Docker and Docker Compose, with several options for
4+
reverse proxy configurations.
5+
6+
## Container Images
7+
8+
Official Conduwuit images are available from GitHub's container registry:
9+
10+
| Image | Notes |
11+
|--------------------------------------|------------------------------------------------|
12+
| ghcr.io/girlbossceo/conduwuit:latest | Stable releases, recommended for production |
13+
| ghcr.io/girlbossceo/conduwuit:main | Latest features, suitable for personal servers |
14+
15+
While the `:latest` tag is recommended for production use, the `:main` tag provides access to the
16+
latest features and fixes. The main branch undergoes significant testing before changes are merged,
17+
making it reliable for personal use while not necessarily "stable" for production environments.
18+
19+
## Quick Start
20+
21+
The simplest way to run Conduwuit is with a basic Docker command:
22+
23+
```bash
24+
docker run -d -p 8448:6167 \
25+
-v db:/var/lib/conduwuit/ \
26+
-e CONDUWUIT_SERVER_NAME="your.server.name" \
27+
-e CONDUWUIT_ALLOW_REGISTRATION=false \
28+
--name conduwuit ghcr.io/girlbossceo/conduwuit:latest
29+
```
30+
31+
However, for production deployments, we recommend using Docker Compose for better maintainability.
32+
33+
## Docker Compose Deployment
34+
35+
We provide two main deployment patterns, depending on how you want to connect to your reverse proxy:
36+
37+
### TCP Port Configuration
38+
39+
This configuration exposes Conduwuit on a TCP port, suitable for when your reverse proxy is on a
40+
different host or when using Kubernetes:
41+
42+
```yaml:docker-compose.yml
43+
version: '3.8'
44+
45+
services:
46+
conduwuit:
47+
cpus: 3
48+
image: ghcr.io/girlbossceo/conduwuit:latest
49+
environment:
50+
CONDUWUIT_CONFIG: '/var/lib/conduwuit/conduwuit.toml'
51+
mem_limit: 4G
52+
ports:
53+
- "6167:6167"
54+
restart: unless-stopped
55+
volumes:
56+
- ./data:/var/lib/conduwuit
57+
```
58+
59+
### Unix Socket Configuration
60+
61+
This configuration uses Unix sockets for improved performance when your reverse proxy is on the same
62+
host:
63+
64+
```yaml:docker-compose.yml
65+
version: '3.8'
66+
67+
services:
68+
conduwuit:
69+
cpus: 3
70+
image: ghcr.io/girlbossceo/conduwuit:latest
71+
environment:
72+
CONDUWUIT_CONFIG: '/var/lib/conduwuit/conduwuit.toml'
73+
mem_limit: 4G
74+
restart: unless-stopped
75+
volumes:
76+
- ./data:/var/lib/conduwuit
77+
- /run/conduwuit:/run/conduwuit
78+
```
79+
80+
For both configurations, create a configuration file in the `data` directory:
81+
82+
```bash
83+
curl -o data/conduwuit.toml https://raw.githubusercontent.com/girlbossceo/conduwuit/main/conduwuit-example.toml
84+
```
85+
86+
See the [configuration guide](config.md) for more information on configuring Conduwuit, and the
87+
[reverse proxy guide](reverse-proxies/README.md) for more information on how to set up a reverse
88+
proxy to handle inbound connections to the server.
89+
90+
## Starting the Server
91+
92+
Once you've chosen and configured your setup:
93+
94+
```bash
95+
# Start the services
96+
docker compose up -d
97+
98+
# View the logs
99+
docker compose logs -f
100+
```

Diff for: ‎src/conduwuit/reverse-proxies/README.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Configuring Reverse Proxies for Conduwuit
2+
3+
A reverse proxy is essential for running Conduwuit in production, handling TLS termination and
4+
providing a secure interface to the internet. This section covers configuration for three popular
5+
reverse proxies:
6+
7+
Before configuring your chosen reverse proxy, you'll need to [set up SSL certificates](ssl.md)
8+
for your domains.
9+
10+
1. [Caddy](caddy.md) - Known for its simplicity and automatic HTTPS
11+
2. [Nginx](nginx.md) - Popular for its performance and flexibility
12+
13+
Choose the guide that matches your preferred reverse proxy. All options will provide:
14+
15+
- TLS termination
16+
- HTTP/2 support
17+
- Proper header forwarding
18+
- WebSocket support for live updates
19+
20+
If you're new to reverse proxies, Caddy might be the easier choice as it handles SSL certificates
21+
automatically. If you're using Docker Compose, Traefik integrates particularly well with container
22+
deployments. However, if you're already familiar with Nginx or need more fine-grained control,
23+
the Nginx configuration will serve you well.

0 commit comments

Comments
 (0)