b429644d9e
- Allow playwright>=1.46.0,<2 in pyproject.toml for Nix compatibility - Add pip constraints.txt to pin playwright==1.46.0 in container builds - Enforce constraints during Docker image build https://chatgpt.com/share/694b0180-2734-800f-830e-44e15d0a527d
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
- Installable via
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 administrator@example.org
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=administrator@example.org
export MATOMO_TOKEN_DESCRIPTION=my-ci-token
matomo-bootstrap
Debug Mode
Enable verbose logs (stderr only):
matomo-bootstrap --debug
How It Works
-
Reachability check
- Waits until Matomo responds over HTTP (any status)
-
Installation (if needed)
- Uses a recorded Playwright flow to complete the Matomo web installer
-
Authentication
- Logs in using the
Login.logmecontroller
- Logs in using the
-
Token creation
- Calls
UsersManager.createAppSpecificTokenAuth
- Calls
-
Output
- Prints the token to stdout (safe for scripting)
End-to-End Tests
Run the full E2E cycle locally:
make e2e
This will:
- Start Matomo + MariaDB via Docker
- Install Matomo headlessly
- Create an API token
- Validate the token via Matomo API
- 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