Quick start

Previous Next

Quick start

This guide starts a native or shared-hosting dashboard. For Docker, use the Docker quickstart.

Requirements

  • PHP 8.3 or newer, Composer, Git, and make
  • MySQL or MariaDB for migrations, event history, alarms, and historical metrics
  • A web server serving public/
  • Cron or an equivalent scheduler

The dashboard renders basic pages without a database, but full monitoring requires one.

1. Run setup

git clone https://github.com/mata-sh/mata-dashboard.git
cd mata-dashboard
make setup

Choose local and the required environment. Setup creates the core configuration files, installs Composer dependencies, and can create the first user.

2. Configure services

Set database credentials in config/db.config.env, then run migrations:

make db-migrate

For alarm decisions, choose one path in config/config.env:

# Native OPA service
ALARM_DECISION_DRIVER=opa
OPA_ALARM_BASE_URI=http://127.0.0.1:3320

make setup offers to install OPA. Run these to install it later, or after declining those prompts:

make setup-opa            # downloads and checksum-verifies bin/opa
make opa-install-service  # installs the systemd unit and starts it (needs sudo)
make opa-status

The unit serves the repository policy/ directory on 127.0.0.1:3320, which is the address OPA_ALARM_BASE_URI expects above.

Hosts that cannot run OPA use the built-in driver instead:

# Shared hosting or another host that cannot run OPA
ALARM_DECISION_DRIVER=builtin

The built-in driver is intentionally limited

It allows critical events and fatal_errors_occurring, using email only, and denies every other candidate. Use the OPA driver wherever it can run.

Configure config/mail.config.env before enabling alarm email.

3. Serve and schedule the dashboard

Point the web server at public/. For shared hosting, install the cron/crontab.shared-hosting.template after replacing APP_ROOT and PHP_BIN.

The scheduled jobs collect node data, persist metrics, evaluate alarms, dispatch email, and clean retained data. Native installations need an equivalent cron configuration; the same template is a usable starting point. The job list is in Add your first server.

The jobs write to logs/ and logs/cron/. Rotate them with cron/logrotate.shared-hosting.conf.template after replacing the placeholder application path; logrotate does not expand APP_ROOT. Install it beside the crontab for a user-owned setup, or as /etc/logrotate.d/mata-dashboard when you have root.

4. Connect a node

Install MATA Node separately on the monitored host, then follow Add your first server. The dashboard pulls from the node; the node never calls back.

5. Verify

If you declined the user prompt during setup, create one now:

make users-create

Open the dashboard, sign in, and run:

make doctor
make db-status

A node may appear before historical chart rows exist. Wait for a successful metrics collection cycle.

Next steps

MATA Docker quickstart