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