212 lines
8.4 KiB
Markdown
212 lines
8.4 KiB
Markdown
# AMMIDS
|
|
**Automated Modular Matrix Infrastructure Deployment Script**
|
|
|
|
> **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)
|
|
|
|
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.
|
|
|
|
## ⚠️ Important Prerequisites
|
|
|
|
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.
|
|
|
|
### Required Dependencies
|
|
|
|
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.
|
|
|
|
---
|
|
*AMMIDS is provided "as is", without warranty of any kind. Use at your own risk.* |