m3tal-core

README

M3TAL System Documentation

Overview

This document provides technical details and operational procedures for the M3TAL system.

Prerequisites

Docker Engine and Docker Compose V2 are strictly REQUIRED and must be installed prior to M3TAL installation and operation. M3TAL internally orchestrates Docker containers using Docker Engine and Docker Compose V2.

APT Installation

To install M3TAL via APT, follow these steps:

# 1. Add the GPG signing key
curl -fsSL https://jakej985-rgb.github.io/m3tal-core/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/m3tal-archive-keyring.gpg

# 2. Add the APT repository
echo "deb [signed-by=/usr/share/keyrings/m3tal-archive-keyring.gpg] https://jakej985-rgb.github.io/m3tal-core stable main" | sudo tee /etc/apt/sources.list.d/m3tal.list

# 3. Install
sudo apt update && sudo apt install -y m3tal

Firewall Considerations

If you are using Traefik for public-facing access (i.e., DASHBOARD_EXPOSE_MODE=traefik or exposing other services via Traefik), ensure that host port 80 (and 443 if HTTPS is configured) is open in your firewall (e.g., ufw allow 80/tcp).

Components

The M3TAL system is comprised of several interconnected components:

• CLI binary (/usr/bin/m3tal): A unified Go binary serving as the single entrypoint for all M3TAL operations. It is installed via APT.
• API daemon (m3tal-api.service): A Go binary running as a systemd service, listening on host-local port 8080. This daemon manages Docker interactions, maintains the SQLite state database, and exposes the M3TAL API routes.
• Dashboard container (m3tal-dashboard): A Python/Flask application running within a Docker container, internally listening on port 8082. It communicates with the M3TAL API daemon via http://host.docker.internal:8080.
• Traefik gateway (routing-compose.yml): A reverse proxy container that exposes services by domain name on host port 80. It utilizes a file provider for dynamic routing configurations.
• Cloudflared (routing-compose.yml): An optional Cloudflare tunnel container, facilitating zero-configuration public internet access for exposed services.

Filesystem Contract

The following table details the critical directories and files within the M3TAL filesystem:

| Path | Purpose yaml services: my-app: image: nginx:alpine labels: - "traefik.enable=true" - "traefik.http.routers.myapp.rule=Host(`app.DOMAIN`)" - "traefik.http.services.myapp.loadbalancer.server.port=80" - "traefik.http.routers.myapp.entrypoints=web" networks: - proxy

Dashboard Access

The M3TAL Dashboard can be accessed in two distinct modes, controlled by the DASHBOARD_EXPOSE_MODE variable in /etc/m3tal/.env:

1. Local Mode (Default)

   • Setting: DASHBOARD_EXPOSE_MODE=local
   • Mechanism: This mode utilizes the m3tal-compose.local.yml override file, which adds a direct Docker port binding, typically ${DASHBOARD_PORT:-8082}:8082.
   • Access: The Dashboard is directly accessible via http://HOST_IP:8082 or http://localhost:8082.
   • Requirements: No Traefik configuration is required. This mode functions out-of-the-box, making it ideal for LAN-only setups, first-time users, or local development and testing.
   • Default Behavior: A new user performing a default M3TAL installation will access the M3TAL Dashboard directly via port 8082, as this is the behavior linked to the default DASHBOARD_EXPOSE_MODE=local setting.

2. Traefik Mode

   • Setting: DASHBOARD_EXPOSE_MODE=traefik
   • Mechanism: This mode utilizes the m3tal-compose.traefik.yml override file. This file applies Traefik labels to the dashboard container, enabling Traefik to route dash.DOMAIN to the dashboard's internal port 8082.
   • Access: The Dashboard is accessible via http://dash.DOMAIN.
   • Requirements: Traefik must be running (m3tal up will start it) and correctly configured. This mode is suitable for domain-based setups and environments where multiple services are managed behind a single reverse proxy.

Quick Demo

To quickly start and interact with core M3TAL services:

• Start the Dashboard specifically:

  m3tal dash up
  

  This command downloads the latest dashboard Docker Compose files and starts the M3TAL Dashboard container, respecting the DASHBOARD_EXPOSE_MODE setting.

• Deploy all M3TAL stacks and user-defined services:

  m3tal up
  

  This command orchestrates and deploys all Docker Compose stacks found as *-compose.yml files within the /docker/ directory. This includes M3TAL's internal control plane components (like Traefik) and any user-defined compose files placed in /docker/.

Service Management

The M3TAL API daemon (m3tal-api.service) runs as a systemd service. Its status and operations can be managed using standard systemctl commands:

• Check API daemon status:

  systemctl status m3tal-api.service
  

• Restart API daemon:

  systemctl restart m3tal-api.service
  

• View API daemon logs:

  journalctl -u m3tal-api.service -f
  

Port Map

The following table lists the primary network ports utilized by the M3TAL system:

Port	Service	Access	Description
80	Traefik HTTP entry point	Public	The public-facing HTTP port for services exposed via Traefik.
8080	M3TAL API daemon (Go)	Host-local	The internal port the M3TAL API daemon listens on.
8081	Traefik dashboard	Host-local only	The internal Traefik dashboard port, accessible only from the host machine.
8082	M3TAL Dashboard	Direct port (local mode) or via Traefik (traefik mode)	The port the M3TAL Dashboard container listens on internally. Access method depends on DASHBOARD_EXPOSE_MODE.

Note: These are the primary M3TAL-managed ports. User-added Docker Compose stacks may expose additional ports on their own, depending on their configurations.