Deploying Synapse

Introduction

Synapse is the reference homeserver implementation for the Matrix protocol, an open standard for secure, decentralized communication. Matrix enables real-time messaging, voice, and video calls with end-to-end encryption and federation between servers.

Key highlights of Synapse:

Federation: Connect with users on other Matrix homeservers worldwide
End-to-End Encryption: Secure messaging with Olm/Megolm encryption
Bridges: Connect to IRC, Slack, Discord, Telegram, and more
Voice/Video: WebRTC-based calls with multiple participants
Rooms and Spaces: Organize conversations in rooms and community spaces
Rich Media: Share files, images, and embedded content
SSO Integration: OIDC, SAML, and LDAP authentication
Admin API: Comprehensive API for server management
Client Ecosystem: Works with Element, FluffyChat, and many other clients

This guide walks through deploying Synapse on Klutch.sh using Docker.

Why Deploy Synapse on Klutch.sh

Deploying Synapse on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Synapse without complex orchestration.

Persistent Storage: Attach persistent volumes for media, database, and configuration.

HTTPS by Default: Secure communication with automatic SSL certificates.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Prerequisites

Before deploying Synapse on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Synapse configuration
Basic familiarity with Docker and containerization concepts
A domain name for your homeserver
A PostgreSQL database (recommended for production)

Deploying Synapse on Klutch.sh

Create Your Repository

Create a new GitHub repository with a Dockerfile for Synapse:

FROM matrixdotorg/synapse:latest

ENV SYNAPSE_SERVER_NAME=${SYNAPSE_SERVER_NAME}
ENV SYNAPSE_REPORT_STATS=no
ENV SYNAPSE_CONFIG_DIR=/data

EXPOSE 8008
EXPOSE 8448

VOLUME ["/data"]

Push to GitHub

Initialize and push your repository to GitHub with your Dockerfile.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8008

Set Environment Variables

Configure the following environment variables:

Variable	Value
`SYNAPSE_SERVER_NAME`	Your Matrix domain (e.g., `matrix.example.com`)
`SYNAPSE_REPORT_STATS`	`no`

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/data`	50 GB	Configuration, database, and media

Deploy Your Application

Click Deploy to start the build process.

Access Synapse

Once deployment completes, your Synapse homeserver is available at your app URL.

Configuration

Generate Configuration

Generate the initial configuration:

docker run -it --rm \
  -v /path/to/data:/data \
  -e SYNAPSE_SERVER_NAME=matrix.example.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

Federation Setup

For federation, configure DNS:

_matrix._tcp.example.com. SRV 10 0 443 matrix.example.com.

Or use a .well-known file on your main domain.

User Registration

Enable registration in homeserver.yaml:

enable_registration: true
enable_registration_without_verification: true  # For testing only

For production, use invite-only or SSO registration.

Connecting Clients

Users can connect with any Matrix client:

Element: Web, Desktop, iOS, Android
FluffyChat: Mobile-focused client
Nheko: Native desktop client
Many more: See matrix.org/clients

Additional Resources

Conclusion

Deploying Synapse on Klutch.sh gives you a fully-featured Matrix homeserver with automatic builds, persistent storage, and secure HTTPS access. Host secure, federated communication for your organization or community.