MIMIC
Modular Infrastructure for Matrix Integration & Configuration
Status: Beta / Experimental
Target OS: Linux (Ubuntu/Debian recommended)
License: AGPL-3.0
Maintainer: Cortex@Fossgate
Source: https://git.fossgate.uk/main/mimic
mimic is an interactive deployment wizard for self-hosting a Matrix homeserver stack. It automates the provisioning and configuration of Synapse, the Matrix Authentication Service (MAS), PostgreSQL, reverse proxying, optional web clients, and Synapse workers — all driven from a single guided setup session.
What it deploys
- Synapse — the Matrix homeserver, with optional generic workers for horizontal scaling
- MAS — Matrix Authentication Service, linked to Synapse via OIDC
- PostgreSQL — dedicated databases and roles for Synapse and MAS
- Reverse proxy — Traefik (automatic TLS) or Nginx (behind an existing proxy)
- Web client — Element, Cinny, or FluffyChat (optional)
- LiveKit — real-time communication stack (optional)
How it works
The setup.sh wizard collects your preferences, writes a .env, then orchestrates three stages: compose file generation (compose_gen.sh), database and config initialisation (config_gen.sh) and worker generation (worker_gen.sh). Everything is template-driven — no hand-editing of YAML required.
Dependencies
mimic targets Linux and has only been tested on Ubuntu 24.04.
| Dependency | Purpose |
|---|---|
| Docker | Container runtime |
| Docker Compose (v2 plugin) | Container orchestration |
| yq | YAML processor (Mike Farah's Go-based yq) |
| openssl | Secret / password generation |
# Docker & Docker Compose plugin
sudo apt update && sudo apt install -y docker.io docker-compose-plugin
# yq — Mike Farah's Go-based version (NOT the Python yq)
sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq
sudo chmod +x /usr/bin/yq
# openssl (usually pre-installed on Ubuntu 24.04)
sudo apt install -y openssl
# Add your user to the docker group (log out/in afterwards)
sudo usermod -aG docker "$USER"
Installation
1. Configure DNS and Firewall
Before running mimic, create A records pointing to your server's public IP for every subdomain you plan to use:
Subdomains shown are defaults, custom values can be configured in the wizard.
| Subdomain | Required? | Purpose |
|---|---|---|
<domain> |
Always | Base Url |
matrix.<domain> |
Always | Synapse homeserver |
auth.<domain> |
Always | Matrix Authentication Service |
app.<domain> |
If a web client is selected | Element / Cinny / FluffyChat |
rtc.<domain> |
If LiveKit is enabled | LiveKit media server |
jwt.<domain> |
If LiveKit is enabled | LiveKit JWT token issuer |
Example for example.org with server IP 203.0.113.42:
example.org IN A 203.0.113.42
matrix.example.org IN A 203.0.113.42
auth.example.org IN A 203.0.113.42
app.example.org IN A 203.0.113.42
rtc.example.org IN A 203.0.113.42
jwt.example.org IN A 203.0.113.42
Firewall Requirements
| Port(s) | Protocol | Required For |
|---|---|---|
| 80 | TCP | Traefik ACME challenges |
| 443 | TCP | HTTPS traffic |
| 10000–20000 | UDP | LiveKit media (if enabled) |
Adjust the UDP range via LIVEKIT_UDP_RANGE in .env if needed.
If using Traefik, ensure ports 80 and 443 are open — Traefik uses HTTP-01 ACME challenges for automatic TLS certificate provisioning.
2. Clone the repository
git clone https://git.fossgate.uk/main/mimic.git
cd mimic
chmod +x setup.sh
3. Run the setup wizard
./setup.sh
The wizard walks you through:
- Base domain — e.g.
example.org - Service toggles — LiveKit on/off, web client choice, proxy choice
- Worker count — number of Synapse generic workers (0 = single-process)
- Credentials — auto-generate secure passwords, or enter them manually
On completion, .env and compose.yaml are written to the project root and all service configs are placed under the volume path (default ./matrix/).
4. Launch
docker compose up -d
Verify the stack is healthy:
docker compose ps