cortex
111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
# mimic
|
|
|
|
**Modular Infrastructure for Matrix Integration & Configuration**
|
|
|
|
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 four 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
|
|
|
|
Before running mimic, create **A records** pointing to your server's public IP for every subdomain you plan to use:
|
|
|
|
| Subdomain | Required? | Purpose |
|
|
|---|---|---|
|
|
| `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`:
|
|
_Subdomains shown are defaults; custom values can be configured in the wizard._
|
|
```
|
|
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
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
|