main/mimic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

project rename and readme update

Browse Source
This commit is contained in:
cortex
2026-05-21 07:50:21 +01:00
parent 2fb51c7d28
commit 099ae71dfd
1 changed files with 102 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+102 -204
View File
@@ -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 | <!-- curl -fsSL https://get.docker.com | sh --> |
| **yq** | YAML processing (Critical) | <!-- wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 && chmod +x /usr/local/bin/yq --> |
| **OpenSSL** | Secure password generation | <!-- apt install openssl --> (Usually pre-installed) |
| **Git** | Repository cloning | <!-- apt install git --> |
| **Sudo** | Permission management | <!-- apt install sudo --> |
> **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:
<!--
git clone https://git.fossgate.uk/main/ammids.git
cd ammids
-->
Run the main orchestrator script:
<!--
chmod +x setup.sh
./setup.sh
-->
**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:
<!--
docker compose up -d
-->
Verify the status:
<!--
docker compose ps
-->
## 📂 Project Structure
<!--
/
├── setup.sh # Main orchestrator
├── .env # Generated environment variables (DO NOT COMMIT)
├── compose.yaml # Generated Docker Compose file
├── init/
│ ├── scripts/
│ │ ├── set_env.sh # Interactive environment generator
│ │ ├── stack_gen.sh # Initializes DB and generates configs
│ │ ├── config_gen.sh # Alternative config generator (legacy)
│ │ ├── compose_gen.sh# Generates the compose file with toggles
│ │ ├── set_compose.sh# Updated compose file generator
│ │ ├── worker_gen.sh # Generates scalable Synapse workers
│ │ ├── set_workers.sh# Generates specific worker configs
│ │ └── link_synapse.sh# Configures OIDC between Synapse & MAS
│ ├── templates/ # YAML templates for workers and compose
│ └── config/ # Log and config templates
└── matrix/ # Data volume (created at runtime)
├── synapse/
├── mas/
└── postgres/
-->
## ⚙️ 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:
<!--
./init/scripts/worker_gen.sh -c 2
-->
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:
<!--
# Linux AMD64
wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
chmod +x /usr/local/bin/yq
-->
### "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:
<!--
docker compose logs matrix-db
-->
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.*
## 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
```