### Enable and Start Caddy Service

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/reverse-proxy-caddy.md

Enables Caddy to start on boot and starts the service immediately.

```bash
sudo systemctl enable --now caddy
```

--------------------------------

### Execute Admin Commands on Startup

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/configuration.md

The `--execute` flag allows running admin commands when Tuwunel starts, useful for initial setup like creating users.

```bash
./tuwunel --execute "users create_user june"
```

--------------------------------

### Example Startup Command Output

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/configuration.md

This is an example of the output when a startup command, such as creating a user, is successfully executed.

```text
INFO tuwunel_service::admin::startup: Startup command #0 completed:
Created user with user_id: @june:girlboss.ceo and password: `<redacted>`
```

--------------------------------

### Example Tuwunel Configuration (TOML)

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/configuration/examples.md

This is an example TOML configuration file for Tuwunel. Ensure all paths are correctly set for your environment.

```toml
{{#include ../../tuwunel-example.toml}}
```

--------------------------------

### Test LiveKit Setup with testmatrix

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Use the `testmatrix` Python package to test the LiveKit setup. This requires your user ID and an access token for your Matrix server.

```bash
# Test the setup (requires testmatrix Python package)
pip install testmatrix
testmatrix -u @your-user:example.com -t YOUR_ACCESS_TOKEN example.com

```

--------------------------------

### Install Docker Buildx

Source: https://github.com/matrix-construct/tuwunel/blob/main/docker/README.md

Installs the docker-buildx package, which is a prerequisite for building Docker images with buildkit.

```bash
apt-get install docker-buildx
```

--------------------------------

### Install Nginx

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/reverse-proxy-nginx.md

Install Nginx using the package manager for your distribution.

```bash
sudo apt install nginx
```

```bash
sudo dnf install nginx
```

```bash
sudo pacman -S nginx
```

--------------------------------

### Execute Admin Command on Startup

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Execute an administrative command, such as creating a user, when Tuwunel starts.

```bash
./tuwunel --execute "users create_user alice"
```

--------------------------------

### Start LiveKit Services and Configure Firewall

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Start the LiveKit services using Docker Compose and open the necessary firewall ports for WebRTC traffic. This includes TCP for signaling and UDP for media.

```bash
# Start LiveKit services
docker compose -f /opt/matrix-rtc/compose.yaml up -d

# Open firewall ports
ufw allow 7881/tcp
ufw allow 50100:50200/udp

```

--------------------------------

### Start Tuwunel Container Service

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/podman-systemd.md

Start the Tuwunel container service using systemd.

```bash
systemctl --user start tuwunel
```

--------------------------------

### Generic Linux Installation (Systemd) for Tuwunel

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Install Tuwunel as a systemd service on Linux. This involves checking CPU optimizations, creating a user, setting up directories, configuring via TOML, and managing the service.

```bash
# 1. Check supported CPU optimization level
cat /proc/cpuinfo | grep -Po '(avx|sse)[235]' | sort -u \
  | sed 's/avx5/v4/;s/avx2/v3/;s/sse3/v2/;s/sse2/v1/' | sort
# Download matching binary, e.g., tuwunel-x86_64-linux-musl-v3

# 2. Create system user
sudo adduser --system tuwunel --group --disabled-login --no-create-home

# 3. Set up directories and permissions
sudo mkdir -p /var/lib/tuwunel/ /etc/tuwunel/
sudo chown -R tuwunel:tuwunel /var/lib/tuwunel/
sudo chmod 700 /var/lib/tuwunel/
sudo chown -R root:root /etc/tuwunel/
sudo chmod -R 755 /etc/tuwunel/

# 4. Create /etc/tuwunel/tuwunel.toml (minimum required fields)
cat > /etc/tuwunel/tuwunel.toml <<'EOF'
[global]
server_name = "example.com"
database_path = "/var/lib/tuwunel"
port = 8008
allow_registration = true
registration_token = "your_secure_token"
allow_federation = true
trusted_servers = ["matrix.org"]

[global.well_known]
client = "https://matrix.example.com"
server = "matrix.example.com:443"
EOF

# 5. Start and enable the systemd service
sudo systemctl start tuwunel
sudo systemctl enable tuwunel

# 6. Health check
curl https://example.com/_tuwunel/server_version
```

--------------------------------

### Start Server in Maintenance Mode for Initial Check

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/troubleshooting.md

Use this command to check if the server starts, indicating no corruption or deep corruption.

```bash
tuwunel --maintenance -O rocksdb_recovery_mode=0
```

--------------------------------

### Start matrix-rtc-livekit Docker Container

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/calls/matrix_rtc.md

Start the matrix-rtc-livekit server using `docker run`. This command mounts a local configuration file and uses the `--network host` option. Ensure the path to `livekit.yaml` is correct.

```bash
docker run -d \
  --restart unless-stopped \
  --name matrix-rtc-livekit \
  --network host \
  -v /opt/matrix-rtc/livekit.yaml:/etc/livekit.yaml:ro \
  livekit/livekit-server:latest \
  --config /etc/livekit.yaml
```

--------------------------------

### Start Tuwunel Service

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/generic.md

Start the Tuwunel systemd service to begin running the application.

```bash
sudo systemctl start tuwunel
```

--------------------------------

### Test Matrix Call Setup

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/calls/matrix_rtc.md

Use the testmatrix utility to verify your call configuration by providing your user ID, access token, and domain.

```bash
testmatrix -u @your-user:yourdomain.com -t YOUR_TOKEN yourdomain.com
```

--------------------------------

### Enable Tuwunel Service on Boot

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/generic.md

Configure the Tuwunel systemd service to start automatically when the system boots up.

```bash
sudo systemctl enable tuwunel
```

--------------------------------

### Enable Livekit Built-In TURN Server (Basic)

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/calls/matrix_rtc.md

Enable the built-in TURN server in your livekit.yaml for basic setup.

```yaml
turn:
  enabled: true
  udp_port: 3478
  relay_range_start: 50300
  relay_range_end: 65535
  domain: matrix-rtc.yourdomain.com
```

--------------------------------

### Coturn Configuration Example

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/calls/turn.md

This is a basic configuration for Coturn. Ensure you replace placeholders with your actual secret key and server domain. The secret key can be generated using `pwgen -s 64 1`.

```conf
use-auth-secret
static-auth-secret=<a secret key>
realm=<your server domain>
```

--------------------------------

### Query Room Timeline PDUs Example

Source: https://github.com/matrix-construct/tuwunel/wiki/Admin-Room-Commands-overview

Example of querying PDUs from the room timeline with a specified limit and sequence number. The sequence number can be negative for backfilled events.

```bash
!admin query room-timeline pdus --limit 1 #tuwunel:grin.hu 0
```

--------------------------------

### Docker Quick Start for Tuwunel

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Run Tuwunel as a Docker container with essential configuration via environment variables. Ensure a reverse proxy handles client HTTPS connections.

```bash
# Pull and run the latest stable release
docker run -d \
  -p 8008:6167 \
  -v db:/var/lib/tuwunel/ \
  -e TUWUNEL_SERVER_NAME="matrix.example.com" \
  -e TUWUNEL_DATABASE_PATH="/var/lib/tuwunel" \
  -e TUWUNEL_PORT="6167" \
  -e TUWUNEL_MAX_REQUEST_SIZE="20000000" \
  -e TUWUNEL_ALLOW_REGISTRATION="true" \
  -e TUWUNEL_REGISTRATION_TOKEN="your_secret_token" \
  -e TUWUNEL_ALLOW_FEDERATION="true" \
  -e TUWUNEL_TRUSTED_SERVERS='["matrix.org"]' \
  -e TUWUNEL_ADDRESS="0.0.0.0" \
  --name tuwunel \
  jevolk/tuwunel:latest

# Verify the server is running
curl https://matrix.example.com/_tuwunel/server_version
curl https://matrix.example.com:8448/_matrix/federation/v1/version
```

--------------------------------

### Tuwunel Command-Line Flags

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Information on using command-line flags to set individual configuration options or run admin commands when starting Tuwunel.

```bash

```

--------------------------------

### Caddyfile Configuration for Tuwunel

Source: https://github.com/matrix-construct/tuwunel/blob/main/README.md

Example Caddyfile configuration for proxying Tuwunel and serving Element web client. Ensure Caddy is reloaded after changes.

```nginx
tuwunel.me, tuwunel.me:8448 {
    reverse_proxy localhost:8008
}
web.tuwunel.me {
    root * /var/www/element/
    file_server
}
```

--------------------------------

### OIDC Server Startup Warning Message

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/oidc-server.md

This warning is logged if an identity provider is configured but `well_known.client` is missing, indicating the OIDC server will not start.

```log
OIDC server (Next-gen auth) requires `well_known.client` to be configured to serve your `identity_provider`.
```

--------------------------------

### Configure Google Provider via Environment Variables

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/providers.md

Configure the Google identity provider using environment variables. This example also marks the Google provider as the default.

```env
TUWUNEL_IDENTITY_PROVIDER__1__BRAND="google"
TUWUNEL_IDENTITY_PROVIDER__1__CLIENT_ID="123456789-abc.apps.googleusercontent.com"
TUWUNEL_IDENTITY_PROVIDER__1__CLIENT_SECRET="GOCSPX-your_secret"
TUWUNEL_IDENTITY_PROVIDER__1__CALLBACK_URL="https://matrix.example.com/_matrix/client/unstable/login/sso/callback/123456789-abc.apps.googleusercontent.com"
TUWUNEL_IDENTITY_PROVIDER__1__DEFAULT="true"
```

--------------------------------

### Static JSON for Client Delegation

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/root-domain-delegation.md

Create a static JSON file at `example.com/.well-known/matrix/client` to point clients to your homeserver's base URL.

```json
{
    "m.homeserver": {
        "base_url": "https://matrix.example.com/"
    }
}
```

--------------------------------

### Configure S3 Object Storage Backend

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Set up S3 as the primary media storage provider. Supports multiple providers for zero-downtime migrations.

```toml
# Use S3 as the primary storage (after migration)
media_storage_providers  = ["media_on_s3"]
store_media_on_providers = []

[global.storage_provider.media_on_s3.s3]
bucket = "my-matrix-media"
region = "us-east-1"
key    = "AKIAIOSFODNN7EXAMPLE"
secret = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

# Self-hosted MinIO / DigitalOcean Spaces / Cloudflare R2
# endpoint         = "https://minio.example.com:9000"
# use_vhost_request = false
```

--------------------------------

### Static JSON for Server Delegation

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/root-domain-delegation.md

Create a static JSON file at `example.com/.well-known/matrix/server` to specify the homeserver domain and port for federation.

```json
{
    "m.server": "matrix.example.com:<PORT>" // e.g. "matrix.example.com:443"
}
```

--------------------------------

### Use Multiple Config Files

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Load multiple configuration files. Settings in later files will override those in earlier files.

```bash
./tuwunel -c /etc/tuwunel/base.toml -c /etc/tuwunel/override.toml
```

--------------------------------

### Start Server in Skip-Any-Corrupted-Record Mode

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/troubleshooting.md

Use for severe corruption cases where the database will be inconsistent. Immediate data salvage is recommended.

```bash
tuwunel --maintenance -O rocksdb_recovery_mode=3
```

--------------------------------

### Admin Command: Enable Room Federation

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/moderation.md

Re-enables inbound PDU handling for a room. Use `--help` for argument details.

```bash
!admin federation enable-room #some_room:example.com
```

--------------------------------

### Start Server in Tolerate-Corrupted-Tail-Records Mode

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/troubleshooting.md

Remediates common corruption by dropping the most recently written record. This is useful after power loss.

```bash
tuwunel --maintenance -O rocksdb_recovery_mode=1
```

--------------------------------

### Verify Nginx Reverse Proxy

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/reverse-proxy-nginx.md

Verify the Nginx reverse proxy setup by making requests to the server version endpoint.

```bash
curl https://matrix.example.com/_tuwunel/server_version
```

```bash
curl https://matrix.example.com:8448/_tuwunel/server_version
```

--------------------------------

### Traefik Network Configuration for Tuwunel

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/reverse-proxy-traefik.md

Configure Traefik to include Tuwunel in its network. Ensure the network name matches your Traefik setup.

```yaml
services:
    tuwunel:
    # ...
    networks:
        - proxy # your traefik network name
networks:
    proxy: # your traefik network name
        external: true
```

--------------------------------

### Nix-based Complement Build and Run

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/development/testing/complement.md

Builds, runs, and outputs logs for Complement using Nix. This command also outputs the OCI image to `result`.

```bash
./bin/complement "$COMPLEMENT_SRC"
```

--------------------------------

### Build and Run Complement Tests Locally

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/development/testing/complement.md

Builds the complement tester and testee images and then runs all complement tests. Ensure Docker with BuildKit and a configured builder is available.

```bash
docker/bake.sh complement-tester complement-testee && docker/complement.sh
```

--------------------------------

### Create and Configure BuildKit Builder

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/development/testing/bake.md

Sets up a named BuildKit builder with specific configurations for platform caching, OCI worker, and garbage collection. The `--allow-insecure-entitlement network.host` flag is necessary for Complement testing.

```bash
cat <<EOF > buildkitd.toml
[system]
  platformsCacheMaxAge = "504h"
[worker.oci]
  enabled = true
  gc = true
  reservedSpace = "64GB"
  maxUsedSpace = "128GB"
[[worker.oci.gcpolicy]]
  reservedSpace = "64GB"
  maxUsedSpace = "128GB"
  all = true
EOF

docker buildx create \
  --name owo \
  --bootstrap \
  --buildkitd-config ./buildkitd.toml \
  --driver docker-container \
  --buildkitd-flags "--allow-insecure-entitlement network.host"
```

--------------------------------

### Configure Well-Known Client for OIDC

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/oidc-server.md

Set the `well_known.client` URL in the `[global.well_known]` section to define the OIDC issuer URL. This is a prerequisite for the OIDC server to start.

```toml
[global.well_known]
client = "https://matrix.example.com"
```

--------------------------------

### Enable Registration with Static Token

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/legacy.md

Enable registration and set a static token for authentication. This is recommended for private or invite-only servers.

```toml
allow_registration = true
registration_token = "o&^uCtes4HPf0Vu@F20jQeeWE7"
```

--------------------------------

### Enable Nginx Configuration

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/reverse-proxy-nginx.md

Enable the Nginx configuration file and test its syntax before reloading Nginx.

```bash
sudo ln -s /etc/nginx/sites-available/tuwunel /etc/nginx/sites-enabled/
```

```bash
sudo nginx -t
```

```bash
sudo systemctl reload nginx
```

```bash
sudo systemctl enable nginx
```

--------------------------------

### Build System Target

Source: https://github.com/matrix-construct/tuwunel/blob/main/docker/README.md

Builds the 'system' target, which is the root target in the Docker Bake configuration. This is a starting point for building the entire image matrix.

```bash
docker/bake.sh system
```

--------------------------------

### Run Docker Compose Services

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/docker.md

Start all services defined in the Docker Compose file in detached mode. Ensure the compose file is configured to your needs before running.

```bash
docker compose up -d
```

--------------------------------

### Basic Trusted Provider Configuration

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/providers.md

Example TOML configuration for a trusted identity provider. Ensure `trusted = true` is only used for self-hosted providers you fully control.

```toml
trusted = true
userid_claims = ["sub"]

```

--------------------------------

### Configure External TURN Server (Coturn)

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/calls/matrix_rtc.md

Add these lines to your coturn.conf to avoid port clashes and set up authentication.

```yaml
min-port=50201
max-port=65535
```

```yaml
static-auth-secret=AUTH_SECRET
```

```yaml
turn_servers:
  - host: turn.yourdomain.com
    port: 5349
    protocol: tls
    secret: "AUTH_SECRET"
```

--------------------------------

### JWT Login Flow

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/jwt.md

Example of a JSON payload to authenticate using a JWT during the login process. The 'type' must be 'org.matrix.login.jwt' and 'token' should contain the signed JWT.

```json
{
  "type": "org.matrix.login.jwt",
  "token": "<jwt>"
}
```

--------------------------------

### Enable Registration with File-Based Tokens

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/legacy.md

Enable registration and specify a file containing registration tokens. This allows for token rotation without restarting the server.

```toml
allow_registration = true
registration_token_file = "/etc/tuwunel/.reg_tokens"
```

--------------------------------

### Configure Tuwunel Server Name

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/deploying/root-domain-delegation.md

Set the `server_name` in the TOML configuration file to your desired public-facing domain. This cannot be changed after initial setup without a database wipe.

```toml
[global]
server_name = "example.com"
```

--------------------------------

### bake.sh Usage with Multiple Targets

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/development/testing/bake.md

Illustrates how to execute multiple build targets sequentially by passing them as arguments to the `bake.sh` script.

```bash
# Multiple targets
docker/bake.sh fmt clippy
```

--------------------------------

### Start Server in Repair Mode

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/troubleshooting.md

Attempts to repair corruption affecting bulk database tables. This mode is not configurable and may remove data. Always back up first.

```bash
tuwunel --maintenance -O rocksdb_repair=true
```

--------------------------------

### Search-then-bind Mode Configuration

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/ldap.md

This recommended bind mode uses a service account to bind to the directory, search for the user, and then re-binds as the user to verify the password. The bind password should be stored in a separate file for security.

```toml
[global.ldap]
enable = true
uri = "ldaps://ldap.example.org:636"
base_dn = "ou=users,dc=example,dc=org"
bind_dn = "cn=ldap-reader,dc=example,dc=org"
bind_password_file = "/etc/tuwunel/.ldap_bind_password"
filter = "(&(objectClass=person)(memberOf=cn=matrix,ou=groups,dc=example,dc=org))"
```

--------------------------------

### Matrix Client Registration with Token

Source: https://context7.com/matrix-construct/tuwunel/llms.txt

Register a new user with a token using a POST request to the client API.

```bash
# Register with token
curl -s -X POST https://matrix.example.com/_matrix/client/v3/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"hunter2","auth":{"type":"m.login.registration_token","token":"your_secret_token"}}'
```

--------------------------------

### Start Server in Point-In-Time Mode

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/troubleshooting.md

Discards recent records back to a non-corrupted point for more severe corruption cases. Clients may need to clear cache and reload.

```bash
tuwunel --maintenance -O rocksdb_recovery_mode=2
```

--------------------------------

### Multiple Identity Providers Configuration

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/authentication/providers.md

Example TOML configuration for setting up multiple identity providers. The `default = true` field designates the provider for the bare SSO redirect.

```toml
[[global.identity_provider]]
brand = "GitHub"
client_id = "github_client_id"
# ...
default = true   # this provider handles the bare SSO redirect

[[global.identity_provider]]
brand = "Google"
client_id = "google_client_id"
# ...

```

--------------------------------

### Nix Build Complement OCI Image

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/development/testing/complement.md

Builds only the Complement OCI image using Nix. The output is a `.tar.gz` file located at `result`.

```bash
nix build .#complement
```

--------------------------------

### Get Media File Info

Source: https://github.com/matrix-construct/tuwunel/blob/main/docs/media/management.md

Retrieves stored metadata for a media file, such as content type, size, creation time, and uploader. Use this to investigate files before deletion.

```bash
!admin media get-file-info <mxc_uri>
```