Native package-based Matrix Synapse installer for Ubuntu and Debian systems.
Synapse Installer is a standalone installer that sets up Matrix Synapse homeserver using official system packages. It provides a complete, production-ready Matrix setup with PostgreSQL, Element Web, and Synapse Admin.
- Native Packages — Uses official system packages (apt) for better integration
- Multi-OS Support — Works on Ubuntu and Debian
- Standalone Capable — Can run independently or as part of the broader Matrix ecosystem
- SSL Integration — Seamless Root Key certificate management for federation
- Modular Design — Each component (manage, ssl, diagnostics) can run standalone
- Element Web Included — Optional Element Web and Synapse Admin installation
- Comprehensive Management — Full configuration management via YAML editing interface
git clone https://github.com/amm1rr/synapse-installer
cd synapse-installer/
./install.sh- Synapse Installation — Installs Matrix Synapse from official sources
- PostgreSQL Setup — Configures PostgreSQL database with optimized settings
SSL Certificates — Integrates with Matrix Installer Root Key or custom certificates- Element Web — Optional web client installation
- Synapse Admin — Optional admin panel installation
- Configuration Management — Interactive YAML-based configuration editor
- Service Management — Complete service lifecycle control
synapse-installer/
├── install.sh # Main installer
├── manage.sh # Configuration management library
├── ssl.sh # SSL certificate management
├── diagnostics.sh # Diagnostic tools (WIP)
├── cache/ # Downloaded packages (gitignored)
├── .gitignore
├── CLAUDE.md # AI assistant guide
└── README.md # This file
| Script | Purpose |
|---|---|
install.sh |
Main Synapse installer |
manage.sh |
Configuration management & YAML editor |
ssl.sh |
SSL certificate management |
diagnostics.sh |
Diagnostic tools (in development) |
┌─────────────────────────────────────────────────────────────────────────┐
│ install.sh │
│ (Orchestrator) │
└────────────────────────────────────┬────────────────────────────────────┘
│ sources
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│ manage.sh │ │ ssl.sh │ │ diagnostics.sh │
│ │ │ │ │ │
│ • YAML utilities │ │ • Certificate │ │ • Service status │
│ • IP whitelist │ │ management │ │ • Health checks │
│ • Management menu │ │ • Root CA install │ │ • Logs viewer │
│ • Shared helpers │ │ • Auto-detection │ │ │
└───────────────────┘ └───────────────────┘ └───────────────────┘
- Package Manager:
apt-get - Synapse Package:
matrix-synapse(from packages.matrix.org) - PostgreSQL:
postgresql - Service Name:
matrix-synapse - Config Directory:
/etc/synapse - Data Directory:
/var/lib/synapse - Service User:
matrix-synapse - Web Server User:
www-data - System CA Path:
/usr/local/share/ca-certificates/
./install.sh# Standalone
./manage.sh# Standalone
./ssl.sh# Standalone (when complete)
./diagnostics.shThe manage.sh script provides comprehensive YAML-based configuration editing:
- General Settings — Server name, listeners, logging
- TLS & Certificates — Certificate management and Root CA installation
- Database Settings — PostgreSQL connection configuration
- Registrations — User registration control and shared secrets
- Federation — Federation rules and certificate verification
- Rooms — Room creation, retention, and moderation
- Media — Media storage, URL preview, and quotas
- Rate Limiting — Rate limiting per-user and per-host
- Statistics — Usage reporting and analytics
The ssl.sh script provides intelligent certificate handling:
- Auto-Detection — Automatically detects certificate files from directory or individual paths
- Multiple Formats — Supports full-chain and separate file formats
- Root CA Integration — Installs Root CA to system trust store for federation
- Certificate Summary — Shows expiry, SANs, issuer, and installation status
- Color-Coded Status — Visual indicators for certificate validity
1. OS Detection
└── Ubuntu/Debian check
2. Prerequisites Check
├── System requirements
└── Required packages (systemd, curl, openssl, yq)
3. PostgreSQL Setup
├── Install PostgreSQL
├── Create database and user
└── Configure connection
4. Synapse Installation
├── Add official Matrix repository
├── Install Synapse package
└── Generate configuration
5. SSL Configuration
├── Install Root CA (if available)
├── Configure certificates
└── Set permissions
6. Optional Components
├── Element Web (optional)
└── Synapse Admin (optional)
7. Service Enablement
├── Enable PostgreSQL
├── Enable Synapse
└── Create admin user
Main Synapse configuration at /etc/synapse/homeserver.yaml
server_name: "matrix.example.com"
pid_file: /var/lib/synapse/homeserver.pid
listeners:
- port: 8448
tls: true
type: http
x_forwarded: true
database:
name: psycopg2
args:
user: synapse
password: <generated>
database: synapsedb
host: localhost
tls_certificate_path: /etc/synapse/matrix.example.com.crt
tls_private_key_path: /etc/synapse/matrix.example.com.key
federation_verify_certificates: true
# local ip support for federation
ip_range_whitelist:[]| Requirement | Minimum | Recommended |
|---|---|---|
| RAM | 512MB | 2GB |
| CPU | 1 core | 2+ cores |
| Disk | 10GB | 50GB+ |
| Dependency | Requirement | Status |
|---|---|---|
| systemd | ✅ required | Native |
| bash | 4+ | Native |
| curl | ✅ required | Native |
| openssl | ✅ required | Native |
| yq | ✅ required | Native |
Ubuntu/Debian:
- postgresql, postgresql-contrib, python3-psycopg2
- matrix-synapse (from packages.matrix.org)
# Run management script
./manage.sh
# Get YAML value programmatically
source manage.sh
yaml_get "server_name" "/etc/synapse/homeserver.yaml"# Run SSL script
./ssl.sh
# Select: Update Synapse Certificates
# Enter path to file or directory (auto-detects)systemctl status matrix-synapsejournalctl -u matrix-synapse -f| File Type | Permissions | Owner |
|---|---|---|
homeserver.yaml |
0640 | matrix-synapse:matrix-synapse |
*.key |
0600 | matrix-synapse:matrix-synapse |
*.crt |
0644 | matrix-synapse:matrix-synapse |
/var/lib/synapse |
0750 | matrix-synapse:matrix-synapse |
When using Root Key certificates:
- Root CA installed to system trust store
- Server certificates configured for Synapse
- Federation enabled with certificate verification
- Automatic trust between servers with same Root Key
# Check certificate expiry
openssl x509 -in /etc/synapse/matrix.example.com.crt -noout -dates
# Verify certificate chain
openssl s_client -connect matrix.example.com:8448 -showcerts
# Check Root CA installation
ls /usr/local/share/ca-certificates/*Root-CA*# Check service status
systemctl status matrix-synapse
# View logs
journalctl -u matrix-synapse -f
# Test configuration
matrix-synapse --config-path /etc/synapse/homeserver.yaml- CLAUDE.md — AI assistant development guide
| Component | Source | URL |
|---|---|---|
| Synapse (Ubuntu/Debian) | packages.matrix.org | https://packages.matrix.org/debian/ |
| Element Web | GitHub Releases | https://github.com/element-hq/element-web/releases |
| Synapse Admin | GitHub Releases | https://github.com/Awesome-Technologies/synapse-admin/releases |
MIT
- Synapse — Matrix homeserver
- Element Web — Matrix web client
- Synapse Admin — Admin panel for Synapse
MIT
- Synapse — Matrix homeserver
- Element Web — Matrix web client
- Synapse Admin — Admin panel for Synapse