m3tal-core

README

M3TAL System Documentation

Overview

This document provides technical details and operational procedures for the M3TAL system. It describes system components, filesystem layout, deployment mechanisms, and service management for both core M3TAL services and user-defined Docker Compose stacks.

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

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

Filesystem Contract

The following table details the primary directories and files managed by the M3TAL system:

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 compose files and Traefik configuration.
/docker	Symlink → /opt/m3tal/stack/. This is the user-facing path for all stack operations.
/docker/users.json	Dashboard credential store. Managed by m3tal dashpass.

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 serves as the canonical source of truth where all stack-related files, including core M3TAL compose files and Traefik configurations, permanently reside. The /docker directory is a symlink alias to /opt/m3tal/stack/, providing a convenient user-facing path 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 configured in /etc/m3tal/.env using m3tal config wizard or m3tal config set KEY value.
3. Run m3tal up to deploy all Docker Compose stacks, including your newly added one.

Quick Demo

To quickly get started with the M3TAL Dashboard:

1. Start the M3TAL Dashboard container specifically:

   m3tal dash up
   

   This command downloads the necessary dashboard compose files and starts the dashboard container according to your DASHBOARD_EXPOSE_MODE setting.
2. Access the dashboard as described in the Dashboard Access section below.
3. To deploy all other M3TAL core stacks (e.g., Traefik) and any user-defined compose files placed in /docker/, run:

   m3tal up
   

   This command orchestrates and deploys all *-compose.yml files present in the /docker/ directory.

Dashboard Access

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

Local Mode (Default)

• Setting: DASHBOARD_EXPOSE_MODE=local (This is the default setting for a new installation).
• Mechanism: Uses the m3tal-compose.local.yml override file, which adds a direct port binding to the dashboard container (${DASHBOARD_PORT:-8082}:8082). Traefik is not required for this mode.
• Access: Directly via http://HOST_IP:8082 or http://localhost:8082.
• Behavior for New Users: A new user performing a default installation will access the dashboard directly via port 8082. This behavior is linked to the default setting DASHBOARD_EXPOSE_MODE=local.

Traefik Mode

• Setting: DASHBOARD_EXPOSE_MODE=traefik
• Mechanism: Uses the m3tal-compose.traefik.yml override file, which adds Traefik labels to the dashboard service. Traefik (if running via m3tal up) then routes requests to dash.${DOMAIN} to the dashboard container on its internal port 8082.
• Access: Via http://dash.DOMAIN (requires Traefik to be running).

Traefik Gateway

Traefik, deployed as a container via routing-compose.yml, functions as the primary reverse proxy for M3TAL. It 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 utilizes a file provider to load dynamic configuration from /docker/dynamic/, enabling hot-reloading of routing rules. For instance, dynamic/api.yml is used to route requests for api.DOMAIN to the M3TAL Go API daemon, which listens on the host-local port 8080, via http://host.docker.internal:8080. Similarly, when DASHBOARD_EXPOSE_MODE=traefik, dash.DOMAIN is routed to the M3TAL Dashboard container.

Exposing a Custom Service via Traefik

To expose a custom user service, my-app, via Traefik, you would add the following labels to its service definition in your Docker Compose file (e.g., my-app-compose.yml):

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
networks:
  proxy:
    external: true

In this example, Traefik is enabled for my-app, routes traffic from app.DOMAIN to the container's internal port 80, and uses the web entrypoint (configured for HTTP on port 80 by default). The service must also be connected to the proxy network, which Traefik is configured to use for discovery.

Service Management

The M3TAL API daemon runs as a systemd service named m3tal-api.service. You can manage this service using standard systemctl commands:

• Check status: systemctl status m3tal-api
• Restart service: systemctl restart m3tal-api
• View logs: journalctl -u m3tal-api -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.