Frequently Asked Questions¶

MAGK (Multipurpose Awareness and Group Kit) is a tactical communications platform designed for military simulation, emergency response training, and coordination operations. It provides real-time position tracking, team management, mission planning, scoring, and integration with TAK (Team Awareness Kit) clients — all managed through a web-based interface.

MAGK serves three primary audiences:

• Military simulation organizations running tactical training exercises
• Emergency response teams coordinating field operations
• Gaming communities using tactical simulation for organized events

The platform supports three user roles: Admins (full platform management), Organizers (event and team management), and Players (event participation and TAK client usage).

Key capabilities include:

• Event creation and lifecycle management (draft → active → completed)
• Team structure with platoons, squads, and roster assignment
• Real-time tactical map with live position tracking via CoT (Cursor on Target)
• Voice communications via Mumble with event-based channels and ATAK Vx integration
• MAGK Node device integration for capture-based gameplay
• Mission and objective planning with scoring rules
• Certificate management for secure TAK client connections
• Workflow automation for registration, certificates, and notifications
• Public live event view with map and scoreboard

MAGK runs as a set of Docker containers. You need:

• Docker (v24+) and Docker Compose (v2.20+)
• Git for cloning the repository
• A domain name with DNS configured (e.g., *.magktech.com)
• Minimum 4 GB RAM and 2 CPU cores for a basic deployment
• Ports 443 (HTTPS), 8087 (TCP CoT), 8089 (SSL CoT), 8443 (Marti API), and 64738 (Mumble voice, when enabled) available

See Prerequisites for the full list.

The .env.template file is the single source of truth for all configuration. Copy it to .env and fill in the required values:

cp .env.template .env

The template is organized into 18 sections (Database, Authentication, TAK Service, etc.). Each variable includes a comment describing its purpose. At minimum, you must set:

• Database credentials (POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD)
• Domain and SSL settings (DOMAIN, SSL_EMAIL)
• Authentication secret (BETTER_AUTH_SECRET)
• LDAP admin password (LDAP_ADMIN_PASSWORD)

See the Configuration Reference for detailed documentation of every variable.

Use openssl to generate secure random values:

# For base64-encoded secrets (e.g., BETTER_AUTH_SECRET)
openssl rand -base64 24

# For hex-encoded secrets (e.g., API keys)
openssl rand -hex 32

Never reuse secrets between staging and production environments. Generate fresh values for each deployment.

Navigate to Admin → User Management in the sidebar. From there you can:

• Create new user accounts with role assignment (Admin, Organizer, Player)
• Activate or deactivate existing accounts
• Assign users to specific events or teams

Users can also self-register through the public registration page or kiosk mode if enabled for an event. See User Management for details.

MAGK automatically generates TLS certificates for TAK client authentication. Navigate to Admin → Certificates to:

• View issued certificates and their expiration dates
• Revoke compromised certificates
• Re-issue certificates for players who need replacements

Certificates are typically issued automatically through Workflows when a registration is approved. You can also issue them manually from the certificates page. See Certificates for the full guide.

The Admin → Dashboard provides an overview of platform metrics including active events, connected users, and system status. For deeper monitoring:

• Admin → Infrastructure shows container health and resource usage
• Admin → Logs displays real-time system logs
• Grafana dashboards (if configured) provide detailed metrics and alerting

See Dashboard and Infrastructure for more information.

1. Navigate to Admin → Events and click Create Event
2. Fill in the event details: name, description, date/time, location
3. Configure game mode, scoring rules, and registration settings
4. Set the event status to Draft while you finalize the setup
5. When ready, click Activate in the status section and confirm the transition

Events follow a lifecycle: Draft → Active → Completed. You can configure teams, missions, and objectives while the event is in draft. See Event Creation for the full walkthrough.

Team structure in MAGK uses a hierarchy: Event → Platoons → Squads → Players.

1. Navigate to your event's team management page
2. Create platoons (e.g., "Blue Force", "Red Force")
3. Create squads within each platoon
4. Assign registered players to squads manually, or let players choose during registration

When the roster is finalized, MAGK automatically provisions TAK server groups and Mumble voice channels matching the team structure. The backend uses "groups" for TAK protocol compatibility, but the admin UI refers to these as "teams." See Team Management.

Scoring is configured per event through scoring rules and game modes. Common scoring sources include:

• Node captures — Points awarded when a team captures a MAGK Node device
• Objective completion — Points for completing mission objectives
• Custom rules — Organizer-defined scoring criteria

Configure scoring from Admin → Scoring and select a game mode from Admin → Game Modes. The live scoreboard updates in real time during active events. See Scoring Rules.

Your organizer will share one of three registration methods:

• Web link — Open the URL in your browser and fill out the form
• QR code — Scan the code with your phone camera to open the registration page
• Kiosk station — Use a shared device at the event venue

Enter your callsign, name, and any other required fields, then submit. Some events require organizer approval before your registration is confirmed. See Registration.

At minimum, you need a smartphone or tablet with a TAK client installed:

• ATAK on Android (Google Play Store or TAK.gov)
• iTAK on iOS (App Store)
• WinTAK on Windows (TAK.gov)

Your device needs GPS/location services enabled and network connectivity (cellular or WiFi) to communicate with the MAGK server. See TAK Client Setup.

MAGK Nodes are physical devices placed in the field during events. To capture a node:

1. Move within range of the node (your organizer will specify the capture radius)
2. Your TAK client detects the node and displays it on the tactical map
3. Follow the capture mechanic defined for your event (proximity-based, timed, etc.)
4. The node status updates in real time on the map and scoreboard

See Node Interaction for detailed capture mechanics and status indicators.

MAGK supports three TAK clients:

ATAK and WinTAK downloads from TAK.gov require a free account. iTAK is available directly from the App Store.

After your registration is approved, you'll receive a certificate package (.zip or .p12 file). The installation process varies by client:

• ATAK: Settings → Network Preferences → Manage Server Connections → Import the .zip file
• iTAK: Settings → Certificates → Import Certificate → Select the .p12 file
• WinTAK: Settings → Network → Manage Server Connections → Import the .zip file

Data packages (.zip) auto-configure the server connection. If using a .p12 file, you'll also need to manually enter the server address and port (8089 for SSL). See TAK Client Setup for step-by-step instructions.

Use port 8089 (SSL) for encrypted connections — this is the recommended default. Port 8087 (TCP) is available for plaintext connections but should only be used if directed by your organizer.

Your organizer provides the server address. The connection protocol should be set to SSL in your TAK client's server configuration.

Try these steps in order:

1. Verify your certificate — Make sure you imported the correct certificate for this event
2. Check the server address and port — Confirm you're using the right address and port 8089 (SSL)
3. Test network connectivity — Ensure port 8089 is reachable from your network. Try switching between WiFi and cellular
4. Restart the client — Close and reopen your TAK application
5. Re-import the certificate — Delete the existing certificate and import it again

If the issue persists, contact your event organizer or see Troubleshooting.

This usually means one of:

• You imported a certificate from a different event — each event may use its own certificate authority
• The certificate has expired — ask your organizer for a new one
• The certificate file was corrupted during download — re-download it from the platform

Delete the existing certificate from your TAK client and re-import the correct one.

Check the following:

1. GPS/Location services — Make sure location permissions are enabled for your TAK client
2. GPS signal — Move outdoors or to an area with clear sky visibility for better GPS reception
3. Server connection — Verify your TAK client shows a connected status
4. Event status — Position sharing only works when the event is in Active status

If your position still doesn't appear, try restarting the TAK client and waiting 30 seconds for the GPS to acquire a fix.

MAGK supports multiple map tile providers:

• OpenStreetMap — Free default, no API key required
• MapTiler — High-quality tiles with satellite imagery (requires API key)
• Mapbox — Full-featured mapping with satellite and terrain layers (requires API key)

Admins configure the map provider in Admin → Settings. The tactical map supports layer switching between street, satellite, and hybrid views depending on the configured provider. See Tactical Map Interface for details.

Enable Mumble in the event's Communications settings, build your roster, and finalize. Channels are automatically provisioned matching your organizational structure (event → platoons → squads + admin channel).

Prerequisites:

1. MUMBLE_ENABLED=true set at the platform level
2. MUMBLE_LDAP_ENABLED=true for player authentication
3. Event has Enable Mumble Voice checked in Communications settings
4. Roster is finalized

See Voice Communications for the full admin guide.

ATAK users get the best experience — voice configuration is bundled into the TAK data package automatically.

Players use their MAGK platform credentials (email and password). LDAP authentication is handled automatically when MUMBLE_LDAP_ENABLED=true.

Credentials are provisioned during roster finalization. Players receive their Mumble username in their registration confirmation email and via QR code enrollment.

Ensure UDP port 64738 is forwarded on your router/firewall. Mumble uses UDP for voice data — without it, audio only works in one direction via TCP fallback.

Also check:

• Microphone permissions are granted to the voice client
• The correct audio input/output devices are selected
• No VPN or network policy is blocking UDP traffic