# 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/ammids](https://git.fossgate.uk/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. Clone the Repository
```
git clone https://git.fossgate.uk/ammids.git
cd ammids
```
### 2. Install Dependencies
Ensure `docker`, `docker-compose`, and `yq` are installed (see **Prerequisites** above).

### 3. Run the Orchestrator
Execute the main setup script. This will guide you through configuration and generate all necessary files.

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.

### 4. 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/set_compose.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`.

## 🛡️ Security Notes

*   **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.

## 🐛 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 `link_synapse.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/ammids/issues)
*   **Feature Requests:** [Discussions](https://git.fossgate.uk/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.*