From 099ae71dfd0f28ef577ac1e4536ad452af2b26c1 Mon Sep 17 00:00:00 2001 From: cortex Date: Thu, 21 May 2026 07:50:21 +0100 Subject: [PATCH] project rename and readme update --- README.md | 306 ++++++++++++++++++------------------------------------ 1 file changed, 102 insertions(+), 204 deletions(-) diff --git a/README.md b/README.md index c26da98..fc2d5a5 100644 --- a/README.md +++ b/README.md @@ -1,212 +1,110 @@ -# AMMIDS -**Automated Modular Matrix Infrastructure Deployment Script** +# mimic -> **Status:** Beta / Experimental -> **Target OS:** Linux (Ubuntu/Debian recommended) -> **License:** AGPL-3.0 -> **Maintainer:** Cortex@Fossgate -> **Source:** [https://git.fossgate.uk/main/ammids](https://git.fossgate.uk/main/ammids) +**Modular Infrastructure for Matrix Integration & Configuration** -AMMIDS is a modular, automated deployment suite designed to spin up a production-ready, upstreamable **Matrix** infrastructure on a fresh VPS. It orchestrates **Synapse**, **Matrix Authentication Service (MAS)**, **PostgreSQL**, and optional components like **LiveKit** and various web clients, all behind a reverse proxy. +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. -## ⚠️ Important Prerequisites +### What it deploys -This script is **tested exclusively on Linux** (specifically Ubuntu 22.04+ and Debian 11+). It relies on GNU-specific utilities (e.g., `sed -i`, `stat -c`) and will **not work** on macOS, BSD, or Windows without significant modification. +- **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) -### Required Dependencies +### How it works -Before running the setup, ensure the following are installed on your VPS: - -| Dependency | Purpose | Install Command (Debian/Ubuntu) | -| :--- | :--- | :--- | -| **Docker & Docker Compose** | Container orchestration | | -| **yq** | YAML processing (Critical) | | -| **OpenSSL** | Secure password generation | (Usually pre-installed) | -| **Git** | Repository cloning | | -| **Sudo** | Permission management | | - -> **Note:** If `yq` is missing, the stack initialization will fail immediately. Ensure it is in your `$PATH` and executable. - -## 🏗️ Architecture Overview - -AMMIDS generates a modular Docker Compose stack with the following components: - -* **Core Services:** - * **Synapse:** The Matrix homeserver (supports generic workers for scaling). - * **MAS (Matrix Auth Service):** Handles OIDC authentication and user sessions. - * **PostgreSQL:** Centralized database for Synapse and MAS. - * **Redis:** Required for Synapse replication and worker communication. -* **Proxy Layer:** - * **Traefik** (Default) or **nginx**: Manages SSL termination and routing. -* **Optional Modules:** - * **LiveKit:** For voice/video call support. - * **Web Clients:** Element, Cinny, or FluffyChat. - * **Workers:** Scalable Synapse workers (Federation Senders, Media Repos, etc.). - -## 🚀 Quick Start - -### 1. DNS Configuration -Before running the installer, ensure your DNS records point to your VPS IP address. You will need the following records: - -| Record Type | Host/Subdomain | Purpose | -| :--- | :--- | :--- | -| `A` | `matrix` | Matrix Homeserver (Synapse) | -| `A` | `auth` | Authentication Service (MAS) | -| `A` | `app` | Web Client (Element/Cinny/FluffyChat) | -| `A` | `rtc` | LiveKit (if enabled) | -| `A` | `jwt` | LiveKit JWT Bridge (if enabled) | - -*These subdomains can be adjusted in the generated .env file.* - -### 2. Clone and Execute -Clone the repository and navigate to the project root: - - - -Run the main orchestrator script: - - - -**What happens during setup:** -1. **Environment Generation:** Prompts for your domain, database credentials, and installation path. Creates `.env`. -2. **Directory Prep:** Creates the data volume directory and fixes ownership. -3. **Stack Initialization:** - * Starts the database and waits for readiness. - * Runs database migration scripts. - * Generates Synapse and MAS configuration files. - * Links Synapse and MAS via Native OIDC. -4. **Compose Generation:** Creates the final `compose.yaml` with your selected modules. - -### 3. Launch the Stack -Once the script completes, start the services: - - - -Verify the status: - - - -## 📂 Project Structure - - - -## ⚙️ Configuration & Customization - -### Environment Variables (`.env`) -The `set_env.sh` script generates a secure `.env` file. Key variables include: -* `DOMAIN`: Your base domain (e.g., `example.org`). -* `HOMESERVER_FQDN`: Your Matrix server address. -* `VOLUME_PATH`: Where data is stored (defaults to `./matrix`). -* `PG_*`: Database credentials (auto-generated if left blank). -* `LIVEKIT_API_KEY`: (Optional) Enable voice/video calls. - -### Adding Workers -To scale your Synapse instance, use the worker generator: - - - -This adds 2 generic workers and updates `compose.yaml`. - -### Changing Web Clients -Re-run `./init/scripts/compose_gen.sh` to toggle between Element, Cinny, FluffyChat, or disable web clients entirely. - -### OIDC Integration -The `config_link.sh` script automatically configures **Native OIDC** between Synapse and MAS. It: -1. Generates a Client ID/Secret in MAS. -2. Injects the OIDC provider configuration into Synapse. -3. Optionally configures **LiveKit** if enabled in `.env`. - -## 🛡️ Proxy & TLS Selection - -During setup, you will be asked to choose a reverse proxy. This choice dictates how TLS/SSL is handled: - -* **Traefik (Default)**: - * **Use this if**: You want the stack to manage SSL certificates automatically via Let's Encrypt. - * **Behavior**: Traefik listens on ports 80/443, handles ACME challenges, and serves HTTPS traffic directly. - * **Requirement**: Ports 80 and 443 must be open to the public internet. - -* **Nginx**: - * **Use this if**: You already have a reverse proxy (e.g., Cloudflare, Caddy, or an existing Nginx instance) handling TLS termination. - * **Behavior**: Nginx in this stack acts purely as an internal router. It does **not** request certificates. - * **Requirement**: Your external proxy must forward traffic to the Nginx container (or the internal services) over HTTP. - -## 🐛 Troubleshooting - -### "Command not found: yq" -The script relies on `yq` for YAML manipulation. Install it manually: - - - -### "compose.yaml not found" -If the script reports success but `compose.yaml` is missing: -1. Check if you are running the script from the correct directory. -2. Ensure `init/templates/compose.yaml.template` exists. -3. Check `/var/log/syslog` or `dmesg` for permission errors on the root directory. - -### Database Not Ready -If the stack fails to start with a database timeout: - - - -Ensure your VPS has sufficient RAM (minimum 2GB recommended for Synapse + Postgres). - -### OIDC Linking Failed -If `config_link.sh` fails: -1. Verify `yq` is installed and functional. -2. Check that `mas/config.yaml` and `synapse/homeserver.yaml` were generated successfully. -3. Ensure `MAS_FQDN` is correctly set in `.env`. - -## 🤝 Contributing - -Contributions are welcome! Please open an issue on the Gitea repository before submitting large changes. - -* **Report Bugs:** [Issues Page](https://git.fossgate.uk/main/ammids/issues) -* **Feature Requests:** [Discussions](https://git.fossgate.uk/main/ammids/discussions) - -## 📜 License - -This project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. - -See the [LICENSE](LICENSE) file for details. +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. --- -*AMMIDS is provided "as is", without warranty of any kind. Use at your own risk.* \ No newline at end of file + +## 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.` | Always | Synapse homeserver | +| `auth.` | Always | Matrix Authentication Service | +| `app.` | If a web client is selected | Element / Cinny / FluffyChat | +| `rtc.` | If LiveKit is enabled | LiveKit media server | +| `jwt.` | 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 +``` + +