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:

# 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

Filesystem Contract

The following paths are central to the M3TAL system's operation and configuration:

Path	Purpose
/etc/m3tal/.env	Primary configuration file. Managed by m3tal config wizard.
/var/lib/m3tal/state.db	SQLite state database. Auto-created by the API daemon.
/opt/m3tal/stack/	Canonical stack directory. Contains Docker Compose files and Traefik dynamic configuration.
/docker	Symlink to /opt/m3tal/stack/. This is the user-facing path for all Docker Compose stack operations.
/docker/users.json	Dashboard credential store. Managed by m3tal dashpass.

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

Deployment Lifecycle

M3TAL orchestrates Docker containers using Docker Compose V2. The m3tal up command is a wrapper around docker compose that operates on all *-compose.yml files located within the /docker/ directory, effectively deploying each as an independent stack.

The /opt/m3tal/stack/ directory is the canonical source of truth where all Docker Compose stack files (e.g., m3tal-compose.yml, routing-compose.yml, and user-defined *-compose.yml files) reside. The /docker/ path is a symbolic link to /opt/m3tal/stack/, serving as the user-facing alias for all stack operations.

Adding a New Stack

To deploy a new Docker Compose stack:

1. Place your Docker Compose file (e.g., my-stack-compose.yml) directly into the /docker/ directory. This file will be automatically included by m3tal up.
2. Ensure any required environment variables for your stack are set in /etc/m3tal/.env (use m3tal config wizard or m3tal config set KEY value).
3. Run m3tal up to deploy your new stack along with all other M3TAL-managed services.

Dashboard Access

The M3TAL Dashboard has two primary access modes, controlled by the DASHBOARD_EXPOSE_MODE variable in /etc/m3tal/.env.

Local Mode (Default)

• Configuration: DASHBOARD_EXPOSE_MODE=local
• Mechanism: When DASHBOARD_EXPOSE_MODE is set to local (the default installation setting), the M3TAL Dashboard container exposes port 8082 directly on the host machine. A new user performing a default installation will access the dashboard directly via http://HOST_IP:8082 or http://localhost:8082.
• Requirements: No Traefik configuration is required for this mode. It uses an internal Docker Compose override file (m3tal-compose.local.yml) to add the direct port binding.
• Best for: LAN-only setups, first-time users, local testing.

Traefik Mode

• Configuration: DASHBOARD_EXPOSE_MODE=traefik
• Mechanism: When DASHBOARD_EXPOSE_MODE is set to traefik, the dashboard container is configured with Traefik labels (via m3tal-compose.traefik.yml), allowing Traefik to route traffic to it. Traefik will route dash.DOMAIN to the dashboard container's internal port 8082.
• Requirements: Access is via http://dash.DOMAIN, where DOMAIN is configured in /etc/m3tal/.env. This mode requires Traefik to be running via m3tal up.
• Best for: Domain-based setups, integrating multiple services behind a reverse proxy.

Traefik Gateway

Traefik acts as the M3TAL system's reverse proxy gateway, facilitating external access to services. Traefik automatically discovers and routes traffic to Docker services by interpreting Traefik labels defined within their Docker Compose service definitions. Crucially, services are not exposed by Traefik by default and require traefik.enable=true along with other relevant labels to be discoverable and routable.

Traefik loads dynamic configuration from files located in /docker/dynamic/ (which is symlinked from /opt/m3tal/stack/dynamic/). This file provider allows for hot-reloading of routing rules.

• API Daemon Routing: Traefik uses a dynamic configuration file (e.g., dynamic/api.yml) to route requests to the M3TAL Go API daemon. For instance, requests to api.DOMAIN are routed to the M3TAL Go API daemon, which listens on the host-local port 8080, specifically targeting http://host.docker.internal:8080 from within the Docker network.
• Dashboard Routing: When DASHBOARD_EXPOSE_MODE=traefik, dash.DOMAIN is routed to the m3tal-dashboard container by Traefik labels defined in m3tal-compose.traefik.yml.

Exposing a Custom User Service via Traefik

To expose your own Docker Compose service through Traefik, add the necessary labels to its service definition:

# /docker/my-app-compose.yml
services:
  my-app:
    image: nginx:alpine
    container_name: my-custom-app
    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

networks:
  proxy:
    external: true # Assumes the 'proxy' network is created by M3TAL's routing stack

After adding this file to /docker/ and running m3tal up, Traefik will automatically configure routing for app.DOMAIN to your my-app service.

Service Management

The M3TAL API daemon is managed as a systemd service, m3tal-api.service.

• Check status: systemctl status m3tal-api.service
• Restart service: systemctl restart m3tal-api.service
• View logs: journalctl -u m3tal-api.service -f

Quick Demo

• Start the Dashboard only: To start only the M3TAL Dashboard container, use m3tal dash up. This command fetches the latest dashboard compose files and starts the dashboard with the appropriate DASHBOARD_EXPOSE_MODE override. This is useful for initial setup or troubleshooting the dashboard in isolation.
• Deploy all M3TAL stacks: The m3tal up command orchestrates and deploys all Docker Compose stacks found in the /docker/ directory, including the M3TAL control plane components (dashboard, routing, etc.) and any user-defined compose files.

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 (mapped to 127.0.0.1:8081).
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.