main/mimic
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
784cca8b27496514eccf3efa9f013768a4cbfcd9
mimic/README.md
T
cortex 784cca8b27 Initial Commit
2026-05-20 10:28:49 +01:00

7.7 KiB
Raw Blame History

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

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

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

Reference in New Issue View Git Blame Copy Permalink