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

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
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
• Feature Requests: Discussions

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the LICENSE file for details.

---

AMMIDS is provided "as is", without warranty of any kind. Use at your own risk.