Synapse Installer

Native package-based Matrix Synapse installer for Ubuntu and Debian systems.

What is Synapse Installer?

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.

Why Use It?

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

Quick Start

git clone https://github.com/amm1rr/synapse-installer
cd synapse-installer/
./install.sh

What It Does

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

Project Structure

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 Overview

Script	Purpose
`install.sh`	Main Synapse installer
`manage.sh`	Configuration management & YAML editor
`ssl.sh`	SSL certificate management
`diagnostics.sh`	Diagnostic tools (in development)

Component Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           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  │  │                   │
    └───────────────────┘  └───────────────────┘  └───────────────────┘

OS Specifications (Ubuntu/Debian)

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/

Running Scripts

Main Installer

./install.sh

Configuration Management

# Standalone
./manage.sh

SSL Certificate Management

# Standalone
./ssl.sh

Diagnostic Tools

# Standalone (when complete)
./diagnostics.sh

Features

Configuration Management

The 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

SSL Certificate Management

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

Screenshots

Main Configuration Menu

SSL Certificate Status

Installation Flow

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

Configuration Files

homeserver.yaml

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:[]

Requirements

System Requirements

Requirement	Minimum	Recommended
RAM	512MB	2GB
CPU	1 core	2+ cores
Disk	10GB	50GB+

Software Dependencies

Dependency	Requirement	Status
systemd	✅ required	Native
bash	4+	Native
curl	✅ required	Native
openssl	✅ required	Native
yq	✅ required	Native

Package Dependencies

Ubuntu/Debian:

postgresql, postgresql-contrib, python3-psycopg2
matrix-synapse (from packages.matrix.org)

Common Tasks

View Configuration

# Run management script
./manage.sh

# Get YAML value programmatically
source manage.sh
yaml_get "server_name" "/etc/synapse/homeserver.yaml"

Update SSL Certificates

# Run SSL script
./ssl.sh
# Select: Update Synapse Certificates
# Enter path to file or directory (auto-detects)

Check Service Status

systemctl status matrix-synapse

View Logs

journalctl -u matrix-synapse -f

Security Considerations

File Permissions

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

Root CA Integration

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

Troubleshooting

Certificate Issues

# 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*

Service Issues

# Check service status
systemctl status matrix-synapse

# View logs
journalctl -u matrix-synapse -f

# Test configuration
matrix-synapse --config-path /etc/synapse/homeserver.yaml

Documentation

CLAUDE.md — AI assistant development guide

External Sources

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

License

MIT

Related Projects

Synapse — Matrix homeserver
Element Web — Matrix web client
Synapse Admin — Admin panel for Synapse

License

MIT

Related Projects

Synapse — Matrix homeserver
Element Web — Matrix web client
Synapse Admin — Admin panel for Synapse

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
docs		docs
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
diagnostics.sh		diagnostics.sh
install.sh		install.sh
manage.sh		manage.sh
ssl.sh		ssl.sh

Amm1rr/Synapse-Installer

Folders and files

Latest commit

History

Repository files navigation

Synapse Installer

What is Synapse Installer?

Why Use It?

Quick Start

What It Does

Project Structure

Script Overview

Component Architecture

OS Specifications (Ubuntu/Debian)

Running Scripts

Main Installer

Configuration Management

SSL Certificate Management

Diagnostic Tools

Features

Configuration Management

SSL Certificate Management

Screenshots

Main Configuration Menu

SSL Certificate Status

Installation Flow

Configuration Files

homeserver.yaml

Requirements

System Requirements

Software Dependencies

Package Dependencies

Common Tasks

View Configuration

Update SSL Certificates

Check Service Status

View Logs

Security Considerations

File Permissions

Root CA Integration

Troubleshooting

Certificate Issues

Service Issues

Documentation

External Sources

License

Related Projects

License

Related Projects

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Languages