From 3217b4639d0c951ff0adce03c042091ec0c7e3f5 Mon Sep 17 00:00:00 2001 From: cortex <1+cortex@noreply.localhost> Date: Wed, 20 May 2026 09:47:52 +0000 Subject: [PATCH] Update README.md --- README.md | 90 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index d9b0afa..c26da98 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ > **Target OS:** Linux (Ubuntu/Debian recommended) > **License:** AGPL-3.0 > **Maintainer:** Cortex@Fossgate -> **Source:** [https://git.fossgate.uk/ammids](https://git.fossgate.uk/ammids) +> **Source:** [https://git.fossgate.uk/main/ammids](https://git.fossgate.uk/main/ammids) 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. @@ -45,20 +45,33 @@ AMMIDS generates a modular Docker Compose stack with the following components: ## 🚀 Quick Start -### 1. Clone the Repository -``` -git clone https://git.fossgate.uk/ammids.git +### 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: + + -### 3. Run the Orchestrator -Execute the main setup script. This will guide you through configuration and generate all necessary files. +Run the main orchestrator script: + **What happens during setup:** 1. **Environment Generation:** Prompts for your domain, database credentials, and installation path. Creates `.env`. @@ -70,21 +83,22 @@ chmod +x setup.sh * Links Synapse and MAS via Native OIDC. 4. **Compose Generation:** Creates the final `compose.yaml` with your selected modules. -### 4. Launch the Stack +### 3. Launch the Stack Once the script completes, start the services: -``` + Verify the status: -``` + + ## 📂 Project Structure -``` + ## ⚙️ Configuration & Customization @@ -119,13 +133,15 @@ The `set_env.sh` script generates a secure `.env` file. Key variables include: ### 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/set_compose.sh` to toggle between Element, Cinny, FluffyChat, or disable web clients entirely. +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: @@ -133,22 +149,30 @@ The `config_link.sh` script automatically configures **Native OIDC** between Syn 2. Injects the OIDC provider configuration into Synapse. 3. Optionally configures **LiveKit** if enabled in `.env`. -## 🛡️ Security Notes +## 🛡️ Proxy & TLS Selection -* **Secrets Management:** The `.env` file contains database passwords and API keys. It is set to `chmod 600` automatically. **Do not commit this file to Git.** -* **Firewall:** Ensure ports `80` and `443` are open for the proxy, and `8448` for Matrix federation. -* **Backups:** Regularly back up the `matrix/` directory and your `.env` file. Losing `.env` means losing access to your database credentials. -* **Permissions:** The scripts attempt to fix directory ownership automatically. If you encounter permission errors, ensure your user has `sudo` privileges. +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: @@ -158,13 +182,15 @@ If the script reports success but `compose.yaml` is missing: ### 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 `link_synapse.sh` fails: +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`. @@ -173,8 +199,8 @@ If `link_synapse.sh` fails: Contributions are welcome! Please open an issue on the Gitea repository before submitting large changes. -* **Report Bugs:** [Issues Page](https://git.fossgate.uk/ammids/issues) -* **Feature Requests:** [Discussions](https://git.fossgate.uk/ammids/discussions) +* **Report Bugs:** [Issues Page](https://git.fossgate.uk/main/ammids/issues) +* **Feature Requests:** [Discussions](https://git.fossgate.uk/main/ammids/discussions) ## 📜 License