Installation Guide¶

This guide walks through deploying the MAGK platform from a fresh clone to a running instance. Complete the Prerequisites checklist before starting.

1. Clone the Repository¶

git clone https://github.com/magktech/magk.git
cd magk

2. Create Your Environment File¶

Copy the template and open it for editing:

cp .env.template .env

The .env.template is the single source of truth for all configuration variables. Every section is commented with descriptions and expected formats. See the Configuration Reference for detailed documentation of each variable.

3. Generate Secrets¶

Several variables require cryptographically random values. Generate them with openssl:

# For passwords (Database, RabbitMQ, LDAP, Grafana)
openssl rand -base64 24

# For auth secrets and API keys (BETTER_AUTH_SECRET, MCP_API_KEY)
openssl rand -hex 32

Replace every GENERATE_WITH_openssl_rand_* placeholder in your .env file with a unique generated value. Each variable needs its own unique secret — do not reuse values across variables.

Required Secrets¶

4. Configure Your Domain¶

Set the DOMAIN and SSL_EMAIL variables to match your DNS setup:

DOMAIN=yourdomain.com
SSL_EMAIL=admin@yourdomain.com

BETTER_AUTH_URL must match your public URL:

BETTER_AUTH_URL=https://yourdomain.com
BETTER_AUTH_TRUSTED_ORIGINS=https://yourdomain.com

5. Deploy¶

MAGK uses Docker Compose with environment-specific override files. Choose the deployment target that matches your environment.

Staging Deployment¶

Staging uses offset ports and a separate project name to run alongside production on the same host.

Create a staging environment file:

cp .env.template .env.staging

Edit .env.staging and set:

DEPLOYMENT_ENV=staging
COMPOSE_PROJECT_NAME=magk-staging
DOMAIN=staging.yourdomain.com
BETTER_AUTH_URL=https://staging.yourdomain.com
BETTER_AUTH_TRUSTED_ORIGINS=https://staging.yourdomain.com

# Database — use staging-specific names to isolate from production
POSTGRES_DB=magk_staging
POSTGRES_USER=magk

Build and start the staging stack:

docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.staging.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.staging \
  --project-directory . \
  build

docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.staging.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.staging \
  --project-directory . \
  up -d

Production Deployment¶

Create a production environment file:

cp .env.template .env.production

Edit .env.production and set:

DEPLOYMENT_ENV=production
COMPOSE_PROJECT_NAME=magk-prod
DOMAIN=yourdomain.com
BETTER_AUTH_URL=https://yourdomain.com
BETTER_AUTH_TRUSTED_ORIGINS=https://yourdomain.com
LOG_LEVEL=INFO

Build and start the production stack:

docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.production.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.production \
  --project-directory . \
  build

docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.production.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.production \
  --project-directory . \
  up -d

6. Environment Isolation with COMPOSE_PROJECT_NAME¶

COMPOSE_PROJECT_NAME is the key to running staging and production side-by-side on the same host. Docker Compose prefixes all container names, volumes, and networks with this value.

Each environment gets its own isolated set of containers, volumes, and networks. Stopping staging does not affect production, and vice versa.

7. SSL/TLS Configuration¶

MAGK uses two layers of TLS for different traffic types.

Traefik — Web Traffic (Let's Encrypt)¶

Traefik automatically provisions and renews TLS certificates from Let's Encrypt for all web-facing services. Configure these variables in your .env file:

DOMAIN=yourdomain.com
SSL_EMAIL=admin@yourdomain.com

Traefik uses the Route53 DNS challenge to obtain a wildcard certificate for *.yourdomain.com. This covers the web app, documentation site, and all subdomains without additional configuration.

Nginx — TAK Client mTLS (Port 8443)¶

TAK clients (ATAK, iTAK, WinTAK) connect to the Marti API over mutual TLS on port 8443. Nginx terminates mTLS using the MAGK Certificate Authority:

• Port 8443 — Marti API with client certificate verification. TAK clients must present a valid certificate signed by the MAGK CA.
• Port 8446 — Certificate enrollment endpoint. Uses a Let's Encrypt certificate (no client cert required) so new devices can request their client certificate.

The TAK service manages the internal CA and issues client certificates. Administrators can manage certificates from the Admin Guide's Certificates page.

Direct TAK Ports¶

The TAK service also listens directly (bypassing both Traefik and Nginx) for CoT protocol traffic:

These ports are configured via TAK_TCP_PORT and TAK_SSL_PORT in your .env file.

8. Optional Integrations¶

The following integrations are disabled by default. Enable them by filling in the relevant environment variables when your deployment requires the functionality.

OAuth Providers (Google, GitHub)¶

Enable OAuth if you want users to sign in with their existing Google or GitHub accounts instead of (or in addition to) LDAP credentials.

When to enable: You have external users who should authenticate via SSO rather than platform-managed accounts.

# Google OAuth — Create credentials at https://console.cloud.google.com/apis/credentials
# Redirect URI: https://yourdomain.com/api/auth/callback/google
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth — Create an OAuth App at https://github.com/settings/developers
# Callback URL: https://yourdomain.com/api/auth/callback/github
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Leave these blank to disable OAuth. OAuth providers can also be configured at runtime from the Admin Settings page.

SMTP Email¶

Enable SMTP if you need the platform to send emails — registration confirmations, password resets, admin notifications, and event invitations.

When to enable: You have an SMTP provider (AWS SES, SendGrid, Mailgun, or any standard SMTP server) and want automated email delivery.

SMTP_HOST=email-smtp.us-west-2.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_SECURE=false
FROM_EMAIL=noreply@yourdomain.com
FROM_NAME=MAGK

SMTP can also be configured at runtime from the Admin Settings page.

Media Streaming (MediaMTX)¶

Enable media streaming if your deployment uses live video feeds from field cameras or drones via RTSP/RTMP.

When to enable: You have RTSP or RTMP video sources that should be viewable from the MAGK tactical map or dashboard.

MTX_PROTOCOLS=tcp
MEDIAMTX_RTSP_PORT=8554
MEDIAMTX_RTMP_PORT=1935

The MediaMTX service is included in the base compose file. Configure the ports and protocol as needed for your video sources.

See the Configuration Reference for the full list of variables in each section.

9. Verifying the Deployment¶

After starting the stack, verify that all services are healthy.

Check Container Status¶

docker ps --filter "name=magk-" --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

All containers should show Up with (healthy) status. Allow 30–60 seconds after startup for health checks to pass.

Access the Web Dashboard¶

Open your browser and navigate to:

• Production: https://yourdomain.com
• Staging: https://staging.yourdomain.com

You should see the MAGK login page. Sign in with the admin credentials you configured.

Test the Documentation Site¶

• Production: https://docs.yourdomain.com
• Staging: https://docs-staging.yourdomain.com

Health Check Endpoints¶

The web service exposes a health endpoint:

curl -s https://yourdomain.com/api/health

View Logs¶

If a service fails to start, check its logs:

# All services
docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.production.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.production \
  --project-directory . \
  logs -f

# Single service
docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.production.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.production \
  --project-directory . \
  logs -f web

10. Updating the Platform¶

To update MAGK to a new version:

# Pull the latest code
git pull origin main

# Rebuild and restart (production example)
docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.production.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.production \
  --project-directory . \
  build

docker compose \
  -f compose/docker-compose.yml \
  -f compose/docker-compose.production.yml \
  -f compose/docker-compose.traefik.yml \
  --env-file .env.production \
  --project-directory . \
  up -d

Check the Changelog for release notes and any migration steps required between versions.

Next Steps¶

• Configuration Reference — Detailed documentation for every .env.template variable
• Admin Quickstart — First steps after deployment
• Certificates — Managing TAK client certificates
• Troubleshooting — Common issues and solutions