Skip to content
Klutch.sh Docs

Deploying Conduit

Introduction

Conduit is a lightweight, fast, and feature-rich Matrix homeserver written in Rust. It provides a modern alternative to Synapse, the reference implementation of the Matrix protocol, while offering significantly better performance characteristics and lower resource requirements.

Matrix is an open standard for decentralized, real-time communication. It enables interoperability between different messaging platforms, allowing users on one Matrix homeserver to communicate seamlessly with users on any other Matrix homeserver—similar to how email works across different providers.

What Makes Conduit Special:

Performance-First Design: Written in Rust with a focus on efficiency, Conduit uses dramatically less memory and CPU compared to Synapse while handling similar workloads.

Simple Deployment: Minimal dependencies and straightforward configuration make deployment accessible to developers of all skill levels.

Federation: Full support for Matrix federation, enabling your users to chat with anyone on any Matrix network.

Feature Complete: Supports direct messages, group chats, encryption, file sharing, and all essential messaging features.

SQLite Support: Can use SQLite for simple deployments or PostgreSQL for scaling to large installations.

Lightweight: Designed to run efficiently on modest hardware, from single-board computers to dedicated servers.

Active Development: Regularly updated with new features and performance improvements.

Community Focus: Part of the larger Matrix ecosystem with strong community support and integrations.

Conduit lets you run your own messaging infrastructure with complete control over data and privacy. Unlike proprietary messaging platforms, there’s no vendor lock-in—your data remains yours, and users can interoperate with the broader Matrix network.

This guide walks you through deploying Conduit on Klutch.sh using Docker. You’ll learn how to configure the server with persistent storage, set up optional database backends, implement security measures, optimize performance, and troubleshoot common deployment issues.

Prerequisites

Before deploying Conduit to Klutch.sh, ensure you have:

  • A Klutch.sh account with dashboard access
  • A GitHub account for repository hosting
  • Docker installed locally for testing (optional but recommended)
  • Basic understanding of Matrix protocol and chat servers
  • A domain name for your homeserver (required for federation)
  • Understanding of SSL/TLS certificates
  • Basic knowledge of networking and firewall configuration

Understanding Conduit Architecture

Technology Stack

Conduit is built on modern technologies optimized for performance:

Backend:

  • Rust programming language for memory safety and performance
  • Tokio async runtime for high concurrency
  • Rocksdb or SQLite for data persistence
  • HTTP/2 support for efficient communication
  • Full Matrix protocol implementation

Storage:

  • SQLite (default, good for small to medium deployments)
  • RocksDB (optimized for high-concurrency scenarios)
  • PostgreSQL (alternative database backend)

Communication:

  • WebSocket support for real-time messaging
  • HTTP API for client-server communication
  • Server-to-server federation protocol
  • End-to-end encryption (E2EE) support

Core Components

Matrix Homeserver: The central server that handles user accounts, messages, and room management

Client-Server API: Enables chat applications to connect and communicate

Server-Server Federation: Allows your homeserver to communicate with other Matrix servers

Room Management: Handles creation, permissions, and message persistence

User Management: Account creation, authentication, and profile management

Encryption: End-to-end encryption for private conversations

Installation and Setup

Step 1: Create Your Project Directory

Start with a dedicated directory for your Conduit deployment:

Terminal window
mkdir conduit-deployment
cd conduit-deployment
git init

Step 2: Create Directory Structure

Set up the necessary directories:

Terminal window
mkdir -p data config

Your project structure will look like:

conduit-deployment/
├── Dockerfile
├── docker-entrypoint.sh
├── conduit.toml
├── .dockerignore
├── .gitignore
└── data/
    └── (persistent storage)

Step 3: Create the Dockerfile

Create a Dockerfile in your project root:

# Use official Rust image for building
FROM rust:latest as builder


WORKDIR /build


# Clone Conduit repository
RUN git clone --depth 1 https://github.com/conduit-rs/conduit.git .


# Build Conduit in release mode
RUN cargo build --release


# Use minimal runtime image
FROM debian:bookworm-slim


# Install runtime dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates \
    curl \
    libssl3 \
    && rm -rf /var/lib/apt/lists/*


# Create application user
RUN useradd -m -u 1000 conduit


# Copy built binary from builder
COPY --from=builder /build/target/release/conduit /usr/local/bin/conduit


# Set working directory
WORKDIR /var/lib/conduit


# Create data directory
RUN mkdir -p /var/lib/conduit/data && \
    chown -R conduit:conduit /var/lib/conduit


# Copy configuration template
COPY conduit.toml /var/lib/conduit/conduit.toml


# Switch to non-root user
USER conduit


# Expose Matrix port
EXPOSE 6167


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:6167/_matrix/client/versions || exit 1


# Start Conduit
CMD ["conduit"]

Step 4: Create Configuration File

Create conduit.toml with basic configuration:

[global]
# Server name - should match your domain
server_name = "example.com"


# Address to bind to (inside container)
address = "0.0.0.0"
port = 6167


# Database settings
database_backend = "sqlite"
database_path = "/var/lib/conduit/data"


# TLS configuration (handled by Klutch.sh)
# Disable internal TLS since Klutch.sh handles SSL/TLS
allow_insecure_origin = true


# Maximum upload size (in bytes)
max_request_size = 20_000_000
# 20MB


# Logging level
log = "info"


# Optional: Rate limiting
# Set to 0 to disable
request_timeout_ms = 30000


# Connection settings
max_concurrent_requests = 1000


[services]
# Optional: Admin API (require auth)
allow_admin_api = false


# Optional: Outbound proxy
# outbound_proxy = ""


[features]
# Enable registration
registration_required = true


# Require approval for new registrations (admin only)
registration_token_required = false


# Allow guest access
allow_guest_access = false

Step 5: Create Entrypoint Script

Create docker-entrypoint.sh for initialization:

#!/bin/bash
set -e


echo "Starting Conduit initialization..."


# Set server name from environment variable if provided
if [ ! -z "$SERVER_NAME" ]; then
    echo "Configuring server name: $SERVER_NAME"
    sed -i "s/server_name = \"example.com\"/server_name = \"$SERVER_NAME\"/g" /var/lib/conduit/conduit.toml
fi


# Set database backend if provided
if [ ! -z "$DATABASE_BACKEND" ]; then
    echo "Setting database backend: $DATABASE_BACKEND"
    sed -i "s/database_backend = \"sqlite\"/database_backend = \"$DATABASE_BACKEND\"/g" /var/lib/conduit/conduit.toml
fi


# Configure PostgreSQL if needed
if [ "$DATABASE_BACKEND" = "postgresql" ]; then
    if [ ! -z "$DATABASE_URL" ]; then
        echo "Configuring PostgreSQL connection"
        sed -i "s|database_path = \"/var/lib/conduit/data\"|database_url = \"$DATABASE_URL\"|g" /var/lib/conduit/conduit.toml
    fi
fi


# Configure max file upload size if provided
if [ ! -z "$MAX_FILE_SIZE" ]; then
    echo "Setting max file size: $MAX_FILE_SIZE"
    sed -i "s/max_request_size = 20_000_000/max_request_size = $MAX_FILE_SIZE/g" /var/lib/conduit/conduit.toml
fi


# Ensure data directory exists and has correct permissions
mkdir -p /var/lib/conduit/data
chown -R conduit:conduit /var/lib/conduit


echo "Conduit initialization complete. Starting server..."


# Execute the main command
exec "$@"

Make it executable:

Terminal window
chmod +x docker-entrypoint.sh

Step 6: Create .dockerignore

Create .dockerignore to exclude unnecessary files:

.git
.gitignore
.env
.env.local
*.log
.DS_Store
.vscode
.idea
README.md
docs/
target/
data/

Step 7: Create .gitignore

Create .gitignore to prevent committing sensitive files:

# Environment
.env
.env.local
.env.production


# Build artifacts
target/
*.o
*.so
*.dylib
*.dll


# Logs
*.log
logs/


# Data
data/
*.db


# OS
.DS_Store
Thumbs.db


# IDE
.vscode/
.idea/
*.swp
*.swo


# Configuration with secrets
conduit.toml.local

Step 8: Local Testing (Optional)

Test your Conduit setup locally:

Terminal window
# Build the image
docker build -t conduit-test .


# Run Conduit locally
docker run -d \
  --name conduit-server \
  -p 6167:6167 \
  -e SERVER_NAME=localhost:6167 \
  -v $(pwd)/data:/var/lib/conduit/data \
  conduit-test


# Wait for startup
sleep 10


# Test the health endpoint
curl http://localhost:6167/_matrix/client/versions


# View logs
docker logs -f conduit-server


# Cleanup
docker stop conduit-server
docker rm conduit-server

Step 9: Commit to GitHub

Push your configuration to GitHub:

Terminal window
git add Dockerfile docker-entrypoint.sh conduit.toml .dockerignore .gitignore
git commit -m "Add Conduit Matrix homeserver Docker configuration"
git branch -M main
git remote add origin https://github.com/yourusername/conduit-deployment.git
git push -u origin main

Deploying to Klutch.sh

Now let’s deploy Conduit to Klutch.sh with proper configuration and persistent storage.

Deployment Steps

  1. Access Klutch.sh Dashboard

    Navigate to klutch.sh/app and sign in with your GitHub account.

  2. Create a New Project

    In the Projects section, click “Create Project” and name it something like “Conduit Matrix Server” or “Chat Infrastructure”.

  3. Create a New App

    Within your project, click “Create App” to begin configuring your Conduit deployment.

  4. Connect Your Repository
    • Select GitHub as your Git source
    • Choose your repository with the Conduit Dockerfile
    • Select the branch to deploy (typically main)

    Klutch.sh will automatically detect the Dockerfile in your repository root.

  5. Configure Traffic Settings
    • Traffic Type: Select HTTP (Conduit serves Matrix protocol over HTTP)
    • Internal Port: Set to 6167 (Conduit’s default listening port)
  6. Configure Environment Variables

    Add the following environment variables to configure your Conduit instance:

    Server Configuration:

    Terminal window
    # Your homeserver domain name (required for federation)
    SERVER_NAME=matrix.example.com
    

    # Description for your server
    SERVER_DESCRIPTION="My Conduit Matrix Server"
    

    # Trusted proxies (Klutch.sh)
    TRUSTED_SERVERS=example-app.klutch.sh

    Database Configuration:

    Terminal window
    # Database backend: sqlite or postgresql
    DATABASE_BACKEND=sqlite
    

    # For PostgreSQL (if using external database):
    DATABASE_URL=postgresql://conduit_user:password@your-db-host:5432/conduit

    Server Behavior:

    Terminal window
    # Maximum upload size in bytes
    MAX_FILE_SIZE=20000000
    # 20MB
    

    # Require registration approval
    REGISTRATION_TOKEN_REQUIRED=false
    

    # Allow guest access
    ALLOW_GUEST_ACCESS=false
    

    # Logging level: off, error, warn, info, debug, trace
    LOG_LEVEL=info
    

    # Maximum concurrent requests
    MAX_CONCURRENT_REQUESTS=1000
    

    # Request timeout in milliseconds
    REQUEST_TIMEOUT_MS=30000

    Optional: Admin Configuration:

    Terminal window
    # Enable admin API (requires authentication)
    ALLOW_ADMIN_API=false
    

    # Admin token (if enabling admin API)
    ADMIN_TOKEN=your-secure-admin-token

    Performance Tuning:

    Terminal window
    # Worker threads (leave blank for auto-detection)
    # Set to number of CPU cores for optimal performance
    CONDUIT_WORKERS=4
    

    # Connection pool size
    CONDUIT_CONNECTION_POOL_SIZE=32

    Security Note:

    • Generate strong, unique values for admin tokens
    • Keep REGISTRATION_TOKEN_REQUIRED=true for controlled growth
    • Never commit environment variables to Git
    • Use strong passwords for any external databases
  7. Configure Persistent Storage

    Conduit needs persistent storage for data:

    Volume 1 - Data Storage:

    • Mount Path: /var/lib/conduit/data
    • Size: 5-20 GB (depends on number of users and messages)

    Guidelines for volume size:

    • Small instance (< 100 users): 5 GB
    • Medium instance (100-500 users): 10 GB
    • Large instance (500+ users): 20+ GB

    Important: Without persistent storage, all user data, messages, and room state will be lost on container restart.

  8. Configure Compute Resources

    Choose appropriate resources based on expected users:

    Small Deployment (< 50 users):

    • CPU: 1 core
    • RAM: 1 GB
    • Suitable for: Testing, small communities

    Medium Deployment (50-200 users):

    • CPU: 2 cores
    • RAM: 2 GB
    • Suitable for: Team messaging, medium communities

    Large Deployment (200-1000 users):

    • CPU: 4 cores
    • RAM: 4 GB
    • Suitable for: Organizations, active communities

    Enterprise (1000+ users):

    • CPU: 8+ cores
    • RAM: 8+ GB
    • Suitable for: Large organizations, public servers

    You can scale based on actual usage patterns.

  9. Deploy the Application

    Click “Create” to start the deployment. Klutch.sh will:

    1. Clone your repository
    2. Build the Docker image (Rust compilation takes ~10-15 minutes)
    3. Configure environment variables
    4. Set up persistent storage
    5. Start the Conduit container
    6. Assign a public URL (e.g., example-app.klutch.sh)
    7. Configure automatic HTTPS with SSL certificates

    Initial deployment may take 15-20 minutes due to Rust compilation.

  10. Monitor Deployment Progress

    Track the deployment:

    • Go to the Deployments tab
    • View real-time build logs (Rust build output is verbose)
    • Wait for status to show “Running”
    • Note that build times are longer than typical applications due to Rust compilation
  11. Configure Your Domain

    Add your custom domain to Klutch.sh:

    1. In Klutch.sh dashboard, go to Domains
    2. Click “Add Custom Domain”
    3. Enter your domain (e.g., matrix.example.com)
    4. Update DNS with CNAME record pointing to example-app.klutch.sh
    5. Wait for DNS propagation and SSL certificate provisioning

    Update Conduit Configuration:

    1. Redeploy with updated SERVER_NAME environment variable
    2. Point to your custom domain: SERVER_NAME=matrix.example.com
  12. Verify Installation

    After deployment, verify Conduit is working:

    1. Check the Matrix client API:

      Terminal window
      curl https://example-app.klutch.sh/_matrix/client/versions

      Should return JSON with supported client API versions.

    2. Check the server info:

      Terminal window
      curl https://example-app.klutch.sh/_matrix/federation/v1/version

      Should return server information.

    3. Test from a Matrix client:

      • Use a client like Element, FluffyChat, or Beeper
      • Set custom homeserver: https://matrix.example.com
      • Create account on your server
      • Verify login works

    4. Check application logs for any errors

Database Configuration

Conduit comes with SQLite as the default database, which works well for most deployments. For larger installations, consider PostgreSQL.

SQLite (Default)

Pros:

  • No external dependencies
  • Easy to backup
  • Low overhead
  • Suitable for thousands of users

Cons:

  • Not ideal for extremely high concurrency
  • Limited scaling options

Configuration:

Terminal window
DATABASE_BACKEND=sqlite
# Data stored in /var/lib/conduit/data directory

PostgreSQL

For deployments with thousands of users or very high message throughput, PostgreSQL provides better performance.

Setup:

Use an external PostgreSQL service or deploy on Klutch.sh:

Recommended Providers:

Configuration:

Terminal window
DATABASE_BACKEND=postgresql
DATABASE_URL=postgresql://conduit_user:secure_password@host:5432/conduit

Create Database and User:

CREATE DATABASE conduit;
CREATE USER conduit_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE conduit TO conduit_user;

Conduit automatically creates required tables and indexes on first run.

Getting Started with Conduit

Joining Your Server

Using a Matrix Client:

  1. Download a client:

  2. Configure custom homeserver:

    • Instead of using the default homeserver, select “Sign in with custom URL”
    • Enter your Conduit server URL: https://matrix.example.com

  3. Create account:

    • Choose username and password
    • Verify email (optional but recommended)
    • Start using Matrix

Creating Rooms

Rooms are the core of Matrix—they’re like channels or group chats.

Creating a Room:

  1. Click the ”+” button or “Create Room”
  2. Enter room name (e.g., “engineering”)
  3. Set room visibility (public or private)
  4. Optionally set topic/description
  5. Add initial members
  6. Create

Room Features:

  • Direct messages (one-on-one chats)
  • Group chats (multiple members)
  • Public rooms (discoverable, anyone can join)
  • Private rooms (invitation-only)
  • Encrypted rooms (end-to-end encryption)

User Management

Creating Users:

Users can register themselves if registration is enabled. Admins can also manage users through admin endpoints.

Admin API (if enabled):

Terminal window
# Create user
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"user_id":"@alice:matrix.example.com","password":"secure"}' \
  https://matrix.example.com/_matrix/client/r0/admin/users/@alice:matrix.example.com/password

User Settings:

  • Username and display name
  • Avatar/profile picture
  • Status message
  • Device management
  • Session management

Federation with Other Servers

Matrix federation allows your users to chat with people on any Matrix homeserver.

How Federation Works:

  1. User on your server sends message to user on another server
  2. Your server looks up the other server’s address
  3. Establishes secure connection to other server
  4. Message is delivered
  5. Other server notifies the recipient

Verify Federation:

Check if your server is reachable:

Terminal window
# From another server or online tool
curl https://matrix.example.com/_matrix/federation/v1/version

Should return your server information.

Connect with Other Users:

In your Matrix client, invite users from other servers:

  • Format: @username:other-server.com
  • Example: @alice:matrix.org (on public matrix.org server)

Security Best Practices

Access Control

Registration Control:

Terminal window
# Require registration approval
REGISTRATION_TOKEN_REQUIRED=true


# Disable guest access
ALLOW_GUEST_ACCESS=false


# Require email verification
EMAIL_VERIFICATION_REQUIRED=true

Admin Endpoints:

Terminal window
# Enable admin API for management
ALLOW_ADMIN_API=true


# Use strong admin token
ADMIN_TOKEN=$(openssl rand -base64 32)

Encryption

Conduit fully supports end-to-end encryption (E2EE). Users can create encrypted rooms where messages are only readable by participants.

E2EE Features:

  • Automatic encryption for private rooms
  • Device verification for security
  • Key backup for recovery
  • Cross-signing for trust

Enable by default in client settings.

Transport Security

HTTPS Requirements:

  • All Matrix communication uses HTTPS
  • Klutch.sh provides automatic SSL certificates
  • Server-to-server federation uses HTTPS
  • Verify custom domain has valid certificate

Certificate Pinning (advanced):

For high-security deployments, implement certificate pinning in clients.

Data Privacy

Retention Policies:

Configure message retention:

# In conduit.toml
# Keep all messages (default)
# Or set specific retention times


# Database encryption at rest (depends on storage provider)

Backups:

Regular backups are essential:

Terminal window
# Backup SQLite database
cp -r /var/lib/conduit/data/db /backups/conduit-$(date +%Y%m%d).db


# Backup PostgreSQL database
pg_dump postgresql://conduit_user:password@host/conduit | gzip > /backups/conduit-$(date +%Y%m%d).sql.gz

User Privacy:

Matrix is designed with privacy in mind:

  • Users control their profile visibility
  • Room access controlled by members
  • Encrypted rooms prevent eavesdropping
  • Users can delete accounts and messages

Regular Maintenance

Update Conduit:

Regularly update to get security patches:

  1. Check for updates: Monitor Conduit releases
  2. Update Dockerfile to new version
  3. Test in staging environment
  4. Deploy update through Klutch.sh
  5. Monitor logs for issues

Verify Security:

  • Review Matrix spec for security implications
  • Monitor Matrix security advisories
  • Keep Rust dependencies updated
  • Test encryption functionality
  • Verify federation security

Performance Optimization

Resource Allocation

CPU:

Conduit is efficient with CPU. Allocate based on user count:

  • < 100 users: 1 core sufficient
  • 100-500 users: 2 cores recommended
  • 500-1000 users: 4 cores recommended
  • 1000+ users: 8+ cores

Memory:

Memory usage depends on:

  • Number of rooms
  • Number of users
  • Message caching
  • Connection count

General guidelines:

  • Small deployments: 1-2 GB RAM
  • Medium deployments: 2-4 GB RAM
  • Large deployments: 4-8+ GB RAM

Database:

SQLite works efficiently up to several thousand users. For larger deployments:

  • Switch to PostgreSQL
  • Use dedicated database server
  • Configure connection pooling
  • Regular vacuuming

Caching

Conduit efficiently caches:

  • User profiles
  • Room state
  • Event data
  • Federation information

Caching is automatic and requires no configuration.

Network Optimization

WebSocket Connections:

Conduit supports WebSocket for efficient real-time messaging. Clients automatically use WebSocket when available.

Compression:

Enable HTTP compression in reverse proxy (not needed if using Klutch.sh’s reverse proxy).

Connection Management:

Terminal window
MAX_CONCURRENT_REQUESTS=1000
REQUEST_TIMEOUT_MS=30000

Tune based on your deployment’s needs.

Troubleshooting

Issue 1: Server Won’t Start

Symptoms: Container exits immediately or shows errors on startup

Solutions:

  1. Check Logs:

    • Go to Klutch.sh dashboard
    • View application logs
    • Look for configuration or startup errors

  2. Verify Configuration:

    • Check SERVER_NAME is set correctly
    • Verify DATABASE_BACKEND is valid
    • Ensure /var/lib/conduit/data is writable

  3. Database Issues:

    • For PostgreSQL: verify connection URL
    • Ensure database exists
    • Check user permissions

  4. Port Configuration:

    • Verify port 6167 is exposed
    • Check no other service uses this port

Issue 2: Federation Not Working

Symptoms: Messages don’t reach other servers, federation fails

Solutions:

  1. Verify Public DNS:

    Terminal window
    dig matrix.example.com
    nslookup matrix.example.com

    Should return correct IP address.

  2. Check Federation Port:

    • Matrix federation uses port 8448 (HTTPS)
    • Klutch.sh handles this through standard HTTPS (443)
    • Verify custom domain is configured

  3. Test Federation:

    Terminal window
    curl https://matrix.example.com/_matrix/federation/v1/version

    Should return JSON with server information.

  4. SSL Certificate:

    • Verify valid certificate installed
    • Check certificate is not self-signed for federation
    • Klutch.sh automatically provisions valid certificates

Issue 3: Can’t Create Account

Symptoms: Registration fails, “registration disabled” errors

Solutions:

  1. Check Registration Settings:

    Terminal window
    # Verify registration is enabled
    REGISTRATION_TOKEN_REQUIRED=false
    # For token-based registration
    REGISTRATION_TOKEN_REQUIRED=true

  2. Admin Token:

    • If token required, provide token during registration
    • Generate token through admin API

  3. Database Issues:

    • Verify database connection works
    • Check database has free space
    • Verify user creation permissions

Issue 4: Slow Message Delivery

Symptoms: Messages delayed, slow real-time updates

Solutions:

  1. Check Resource Usage:

    • Monitor CPU usage in Klutch.sh
    • Check memory usage
    • Look for bottlenecks

  2. Upgrade Resources:

    • Increase CPU cores
    • Increase RAM
    • Reduce user load or increase server capacity

  3. Database Performance:

    • For SQLite: ensure disk is fast
    • For PostgreSQL: check query performance
    • Monitor database connections

  4. Connection Limits:

    • Increase MAX_CONCURRENT_REQUESTS if needed
    • Check for connection pool exhaustion

Issue 5: High Memory Usage

Symptoms: Server consuming excessive memory, OOM errors

Solutions:

  1. Identify Memory Leaks:

    • Monitor memory usage over time
    • Check for rapidly growing memory
    • Review Conduit logs

  2. Reduce User Load:

    • Limit concurrent users
    • Reduce number of rooms
    • Enable message retention limits

  3. Upgrade Resources:

    • Allocate more RAM
    • Upgrade to larger instance
    • Scale horizontally if needed

  4. Database Tuning:

    • Optimize database queries
    • Reduce cache size if needed
    • Monitor database memory usage

Issue 6: TLS/Certificate Errors

Symptoms: “Certificate invalid”, federation fails, security warnings

Solutions:

  1. Verify Certificate:

    Terminal window
    curl -v https://matrix.example.com/_matrix/client/versions
    # Check certificate details

  2. DNS Configuration:

    • Verify DNS records are correct
    • Wait for propagation if recently changed
    • Check CNAME points to Klutch.sh domain

  3. Klutch.sh SSL:

    • Give Klutch.sh time to provision certificate
    • May take 5-10 minutes after DNS updates
    • Check for ACME renewal issues

  4. Client Configuration:

    • Ensure client trusts certificate authority
    • Update client certificates if using self-signed (not recommended)
    • Clear client cache

Issue 7: Database Corruption

Symptoms: “Database locked”, corruption errors, failed queries

Solutions:

  1. For SQLite:

    • Stop Conduit server
    • Check database file integrity: sqlite3 data/conduit.db "PRAGMA integrity_check;"
    • Restore from backup if corrupted

  2. For PostgreSQL:

    • Check PostgreSQL logs for corruption
    • Run REINDEX if needed
    • Contact database provider

  3. Prevent Corruption:

    • Use persistent volumes for reliability
    • Regular backups
    • Proper shutdown procedures
    • Avoid force-killing containers

Issue 8: Room/Message Issues

Symptoms: Can’t create rooms, missing messages, room join failures

Solutions:

  1. Check Permissions:

    • Verify user has creation permissions
    • Check room access controls
    • Verify user not banned

  2. Database Issues:

    • Ensure database has free space
    • Check user quota not exceeded
    • Verify room state consistency

  3. Clear Cache:

    • Restart server to clear in-memory cache
    • Force clients to resync
    • Rebuild room state if needed

Issue 9: Client Connection Issues

Symptoms: Clients can’t connect, “connection refused”, timeouts

Solutions:

  1. Verify Server Running:

    • Check app status in Klutch.sh
    • View application logs
    • Verify container is healthy

  2. Check Homeserver URL:

    • Verify correct URL in client: https://matrix.example.com
    • Ensure protocol is HTTPS
    • Check custom domain if using

  3. Firewall/Network:

    • Verify ports are open
    • Check ISP isn’t blocking connections
    • Try from different network

  4. Client Issues:

    • Clear client cache and cookies
    • Update to latest client version
    • Try different client to isolate issue

Issue 10: Admin API Issues

Symptoms: Admin commands fail, authorization errors

Solutions:

  1. Enable Admin API:

    Terminal window
    ALLOW_ADMIN_API=true

  2. Verify Admin Token:

    • Ensure token is correctly set
    • Token must be sent in Authorization header
    • Verify header format: Authorization: Bearer TOKEN

  3. Check Permissions:

    • Verify admin token has necessary permissions
    • Some operations require full admin rights
    • Review operation logs

Custom Domains

Using a custom domain is essential for Matrix federation.

Step 1: Add Domain in Klutch.sh

  1. Go to your Conduit app in Klutch.sh dashboard
  2. Navigate to Domains
  3. Click “Add Custom Domain”
  4. Enter your domain (e.g., matrix.example.com)
  5. Save

Step 2: Configure DNS

Update your domain provider:

Type: CNAME
Name: matrix (if subdomain) or @ (for root)
Value: example-app.klutch.sh
TTL: 3600

Step 3: Update Conduit Configuration

Set the server name environment variable:

Terminal window
SERVER_NAME=matrix.example.com

Redeploy the application for the change to take effect.

Step 4: Verify Setup

  1. Wait for DNS propagation (up to 1 hour)

  2. Test DNS:

    Terminal window
    nslookup matrix.example.com

  3. Verify SSL certificate (wait a few minutes for provisioning)

  4. Test federation:

    Terminal window
    curl https://matrix.example.com/_matrix/federation/v1/version

  5. Update client homeserver URL

Production Best Practices

Backup Strategy

What to Backup:

  1. Database (SQLite or PostgreSQL)
  2. User data and keys
  3. Configuration files

Backup Schedule:

  • Daily: Database backup
  • Weekly: Full system backup
  • Monthly: Archival backup

Backup Commands:

Terminal window
# SQLite backup
cp -r /var/lib/conduit/data /backups/conduit-data-$(date +%Y%m%d)


# PostgreSQL backup
pg_dump DATABASE_URL | gzip > /backups/conduit-$(date +%Y%m%d).sql.gz


# Store in safe location
# Consider cloud storage backup

Restore Procedures:

  • Document restoration steps
  • Test recovery monthly
  • Keep offline backup copies
  • Verify backup integrity

Monitoring and Alerting

Key Metrics:

  • CPU and memory usage
  • Database performance
  • Message throughput
  • User count
  • Disk space
  • Error rates

Alerts:

  • High CPU (> 80% sustained)
  • High memory (> 90%)
  • Disk space low (< 10% free)
  • Database errors
  • Federation failures

Scaling Strategies

Vertical Scaling (recommended for most):

  • Increase CPU cores
  • Increase RAM
  • Upgrade storage
  • Improve database performance

When to Scale:

  • CPU consistently > 70%
  • Memory > 80%
  • Response times increasing
  • Database getting slow

Horizontal Scaling (for very large deployments):

  • Multiple Conduit instances
  • Load balancer
  • Shared database (PostgreSQL)
  • Shared media storage

Security Maintenance

Regular Tasks:

Weekly:

  • Monitor error logs
  • Check federation status
  • Verify TLS certificates

Monthly:

  • Security audit
  • Access control review
  • Backup verification

Quarterly:

  • Major updates
  • Security assessment
  • Performance review

Annually:

  • Disaster recovery test
  • Capacity planning
  • Strategy evaluation

Additional Resources

Conclusion

Deploying Conduit on Klutch.sh gives you a lightweight, efficient Matrix homeserver with complete control over your messaging infrastructure. You’ve learned how to build a production-ready Dockerfile with multi-stage compilation, configure the server with persistent storage for user data and messages, set up optional PostgreSQL for scaling, implement security best practices for user authentication and encryption, optimize performance for your user base, troubleshoot common deployment issues, and configure federation with the broader Matrix network.

Conduit’s Rust implementation provides significant advantages in resource efficiency compared to other Matrix homeservers. Your deployment can handle thousands of users while consuming minimal server resources.

With Klutch.sh’s straightforward deployment, you can focus on building your community rather than managing infrastructure. Your server is running on reliable infrastructure with automatic HTTPS, scalable resources, and global distribution.

Matrix federation enables your users to communicate with the broader Matrix network—no walled garden, no vendor lock-in. Your users can chat with anyone on any Matrix homeserver, just like email works across providers.

Start small, monitor your usage patterns, and scale as your community grows. Conduit’s lightweight design means you can provide high-quality messaging infrastructure without breaking the bank.

For questions, community support, or to learn more about the Matrix protocol, check out the Conduit website, Matrix specification, and active community forums.