127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
# 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](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 |
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
<span style="color: #bdac57">_Subdomains shown are defaults, custom values can be configured in the wizard._</span>
|
||
|
||
| 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
|
||
|
||
```bash
|
||
git clone https://git.fossgate.uk/main/mimic.git
|
||
cd mimic
|
||
chmod +x setup.sh
|
||
```
|
||
|
||
### 3. Run the setup wizard
|
||
|
||
```bash
|
||
./setup.sh
|
||
```
|
||
|
||
The wizard walks you through:
|
||
|
||
1. **Base domain** — e.g. `example.org`
|
||
2. **Service toggles** — LiveKit on/off, web client choice, proxy choice
|
||
3. **Worker count** — number of Synapse generic workers (0 = single-process)
|
||
4. **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
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
Verify the stack is healthy:
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
|