matomo-bootstrap 1.0.0

Headless bootstrap tooling for Matomo (installation + API token provisioning)

matomo-bootstrap

Headless bootstrap tooling for Matomo Automates installation (via recorded Playwright flow) and API token provisioning for fresh Matomo instances.

This tool is designed for CI, containers, and reproducible environments, where no interactive browser access is available.

---

Features

• 🚀 Fully headless Matomo installation

  • Drives the official Matomo web installer using Playwright
  • Automatically skips installation if Matomo is already installed

• 🔐 API token provisioning

  • Creates an app-specific token via authenticated Matomo session
  • Compatible with Matomo 5.3.x Docker images

• 🧪 E2E-tested

  • Docker-based end-to-end tests included

• ❄️ First-class Nix support

  • Flake-based packaging
  • Reproducible CLI and dev environments

• 🐍 Standard Python CLI

  • Installable via pip
  • Clean stdout (token only), logs on stderr

---

Requirements

• A running Matomo instance (e.g. Docker)

• For fresh installs:

  • Chromium (managed automatically by Playwright)

---

Installation

Using Nix (recommended)

If you use Nix with flakes:

nix run github:kevinveenbirkenbach/matomo-bootstrap

Install Playwright’s Chromium browser (one-time):

nix run github:kevinveenbirkenbach/matomo-bootstrap#matomo-bootstrap-playwright-install

This installs Chromium into the user cache used by Playwright.

---

Using Python / pip

Requires Python ≥ 3.10

pip install matomo-bootstrap

Install Chromium for Playwright:

python -m playwright install chromium

---

Usage

CLI

matomo-bootstrap \
  --base-url http://127.0.0.1:8080 \
  --admin-user administrator \
  --admin-password AdminSecret123! \
  --admin-email [e-mail]

On success, the command prints only the API token to stdout:

6c7a8c2b0e9e4a3c8e1d0c4e8a6b9f21

---

Environment Variables

All options can be provided via environment variables:

export MATOMO_URL=http://127.0.0.1:8080
export MATOMO_ADMIN_USER=administrator
export MATOMO_ADMIN_PASSWORD=AdminSecret123!
export MATOMO_ADMIN_EMAIL=[e-mail]
export MATOMO_TOKEN_DESCRIPTION=my-ci-token

matomo-bootstrap

---

Debug Mode

Enable verbose logs (stderr only):

matomo-bootstrap --debug

---

How It Works

1. Reachability check

   • Waits until Matomo responds over HTTP (any status)

2. Installation (if needed)

   • Uses a recorded Playwright flow to complete the Matomo web installer

3. Authentication

   • Logs in using the Login.logme controller

4. Token creation

   • Calls UsersManager.createAppSpecificTokenAuth

5. Output

   • Prints the token to stdout (safe for scripting)

---

End-to-End Tests

Run the full E2E cycle locally:

make e2e

This will:

1. Start Matomo + MariaDB via Docker
2. Install Matomo headlessly
3. Create an API token
4. Validate the token via Matomo API
5. Tear everything down again

---

Project Status

• ✔ Stable for CI / automation
• ✔ Tested against Matomo 5.3.x Docker images
• ⚠ Installer flow is UI-recorded (robust, but may need updates for future Matomo UI changes)

---

Author

Kevin Veen-Birkenbach 🌐 https://www.veen.world/

---

License

MIT License See LICENSE