Skip to content

Prerequisites

This page covers the software, domain, and DNS requirements for deploying MAGK. For hardware specifications and port requirements, see System Requirements.

Operating System

MAGK deploys on any Linux distribution that supports Docker. The following are recommended for production:

Distribution Version Notes
Ubuntu 22.04 LTS Most tested; long-term support until 2027
Debian 12 (Bookworm) Stable and lightweight

macOS and Windows (via WSL2) work for local development but are not supported for production deployments.

Docker Engine

Docker Engine 24.0 or later is required.

Install Docker Engine following the official installation guide for your distribution.

After installation, add your user to the docker group so you can run commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Verify the installation:

docker --version
# Docker version 24.0.0 or later

Docker Compose

Docker Compose v2.20 or later is required as a Docker CLI plugin.

Compose Plugin vs Standalone

MAGK uses the Compose plugin (docker compose) — not the legacy standalone docker-compose binary. The plugin ships with Docker Engine on most distributions. If it is missing, install it separately via the Compose plugin instructions.

Verify the installation:

docker compose version
# Docker Compose version v2.20.0 or later

Git

Git 2.30 or later is required to clone the MAGK repository.

git --version
# git version 2.30.0 or later

Most Linux distributions ship a compatible version. If yours is older, install from the Git downloads page or use a PPA:

# Ubuntu/Debian
sudo add-apt-repository ppa:git-core/ppa
sudo apt update && sudo apt install git

Domain and DNS

MAGK requires a registered domain with DNS management access. Traefik uses the domain to route traffic and provision TLS certificates automatically via Let's Encrypt.

DNS Records

Create a wildcard A record pointing to your server's public IP address:

Record Type Host Value
A *.yourdomain.com Your server's public IP

The wildcard record covers all MAGK subdomains — the web app, documentation site, staging environment, and any future services — without additional DNS entries.

Example

If your domain is magktech.com and your server IP is 203.0.113.10:

Type Host Value
A *.magktech.com 203.0.113.10

This routes magktech.com, docs.magktech.com, staging.magktech.com, and all other subdomains to your server.

SSL Email

Provide a valid email address in the SSL_EMAIL environment variable. Traefik uses this email when requesting TLS certificates from Let's Encrypt. You will receive expiration warnings if certificate renewal fails.

SSL_EMAIL=admin@yourdomain.com

Let's Encrypt Rate Limits

Let's Encrypt enforces rate limits on certificate issuance. Avoid repeatedly tearing down and recreating your deployment during initial setup — use staging certificates first if testing.

Checklist

Before proceeding to installation, confirm:

  • [x] Linux server running Ubuntu 22.04 LTS or Debian 12
  • [x] Docker Engine 24.0+ installed
  • [x] Docker Compose 2.20+ plugin installed
  • [x] Git 2.30+ installed
  • [x] Domain registered with DNS management access
  • [x] Wildcard A record (*.yourdomain.com) pointing to server IP
  • [x] Valid email address for Let's Encrypt SSL certificates
  • [x] Server meets hardware requirements

Next Steps