matomo-bootstrap 1.0.0__tar.gz

matomo_bootstrap-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Kevin Veen-Birkenbach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

matomo_bootstrap-1.0.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: matomo-bootstrap
+Version: 1.0.0
+Summary: Headless bootstrap tooling for Matomo (installation + API token provisioning)
+Author-email: Kevin Veen-Birkenbach <kevin@veen.world>
+License: MIT
+Project-URL: Homepage, https://github.com/kevinveenbirkenbach/matomo-bootstrap
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40.0
+Provides-Extra: e2e
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# matomo-bootstrap
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+
+
+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:
+
+```bash
+nix run github:kevinveenbirkenbach/matomo-bootstrap
+```
+
+Install Playwright’s Chromium browser (one-time):
+
+```bash
+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**
+
+```bash
+pip install matomo-bootstrap
+```
+
+Install Chromium for Playwright:
+
+```bash
+python -m playwright install chromium
+```
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+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:
+
+```text
+6c7a8c2b0e9e4a3c8e1d0c4e8a6b9f21
+```
+
+---
+
+### Environment Variables
+
+All options can be provided via environment variables:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+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/](https://www.veen.world/)
+
+---
+
+## License
+
+MIT License
+See [LICENSE](LICENSE)

matomo_bootstrap-1.0.0/README.md

@@ -0,0 +1,183 @@
+# matomo-bootstrap
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+
+
+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:
+
+```bash
+nix run github:kevinveenbirkenbach/matomo-bootstrap
+```
+
+Install Playwright’s Chromium browser (one-time):
+
+```bash
+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**
+
+```bash
+pip install matomo-bootstrap
+```
+
+Install Chromium for Playwright:
+
+```bash
+python -m playwright install chromium
+```
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+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:
+
+```text
+6c7a8c2b0e9e4a3c8e1d0c4e8a6b9f21
+```
+
+---
+
+### Environment Variables
+
+All options can be provided via environment variables:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+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/](https://www.veen.world/)
+
+---
+
+## License
+
+MIT License
+See [LICENSE](LICENSE)

matomo_bootstrap-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "matomo-bootstrap"
+version = "1.0.0"
+description = "Headless bootstrap tooling for Matomo (installation + API token provisioning)"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Kevin Veen-Birkenbach", email = "kevin@veen.world" }]
+license = { text = "MIT" }
+urls = { Homepage = "https://github.com/kevinveenbirkenbach/matomo-bootstrap" }
+
+dependencies = [
+  "playwright>=1.40.0",
+]
+
+# Provides a stable CLI name for Nix + pip installs:
+[project.scripts]
+matomo-bootstrap = "matomo_bootstrap.__main__:main"
+
+[project.optional-dependencies]
+e2e = []
+
+dev = [
+  "ruff",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

matomo_bootstrap-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

matomo_bootstrap-1.0.0/src/matomo_bootstrap/__init__.py

@@ -0,0 +1,8 @@
+"""
+matomo-bootstrap
+Headless bootstrap tooling for Matomo:
+- readiness checks
+- admin/API token provisioning
+"""
+
+__all__ = []

matomo_bootstrap-1.0.0/src/matomo_bootstrap/__main__.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import sys
+
+from .cli import parse_args
+from .config import config_from_env_and_args
+from .errors import BootstrapError
+from .service import run
+
+
+def main() -> int:
+    args = parse_args()
+
+    try:
+        config = config_from_env_and_args(args)
+        token = run(config)
+        print(token)
+        return 0
+    except ValueError as exc:
+        # config validation errors
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 2
+    except BootstrapError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"[FATAL] {type(exc).__name__}: {exc}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

matomo_bootstrap-1.0.0/src/matomo_bootstrap/cli.py

@@ -0,0 +1,50 @@
+import argparse
+import os
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        description="Headless bootstrap tool for Matomo (installation + API token provisioning)"
+    )
+
+    p.add_argument(
+        "--base-url",
+        default=os.environ.get("MATOMO_URL"),
+        help="Matomo base URL (or MATOMO_URL env)",
+    )
+    p.add_argument(
+        "--admin-user",
+        default=os.environ.get("MATOMO_ADMIN_USER"),
+        help="Admin login (or MATOMO_ADMIN_USER env)",
+    )
+    p.add_argument(
+        "--admin-password",
+        default=os.environ.get("MATOMO_ADMIN_PASSWORD"),
+        help="Admin password (or MATOMO_ADMIN_PASSWORD env)",
+    )
+    p.add_argument(
+        "--admin-email",
+        default=os.environ.get("MATOMO_ADMIN_EMAIL"),
+        help="Admin email (or MATOMO_ADMIN_EMAIL env)",
+    )
+    p.add_argument(
+        "--token-description",
+        default=os.environ.get("MATOMO_TOKEN_DESCRIPTION", "matomo-bootstrap"),
+        help="App token description",
+    )
+    p.add_argument(
+        "--timeout",
+        type=int,
+        default=int(os.environ.get("MATOMO_TIMEOUT", "20")),
+        help="Network timeout in seconds (or MATOMO_TIMEOUT env)",
+    )
+    p.add_argument("--debug", action="store_true", help="Enable debug logs on stderr")
+
+    # Optional (future use)
+    p.add_argument(
+        "--matomo-container-name",
+        default=os.environ.get("MATOMO_CONTAINER_NAME"),
+        help="Matomo container name (optional; also MATOMO_CONTAINER_NAME env)",
+    )
+
+    return p.parse_args()

matomo_bootstrap-1.0.0/src/matomo_bootstrap/config.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    admin_user: str
+    admin_password: str
+    admin_email: str
+    token_description: str = "matomo-bootstrap"
+    timeout: int = 20
+    debug: bool = False
+    matomo_container_name: str | None = (
+        None  # optional, for future console installer usage
+    )
+
+
+def config_from_env_and_args(args) -> Config:
+    """
+    Build a Config object from CLI args (preferred) and environment variables (fallback).
+    """
+    base_url = getattr(args, "base_url", None) or os.environ.get("MATOMO_URL")
+    admin_user = getattr(args, "admin_user", None) or os.environ.get(
+        "MATOMO_ADMIN_USER"
+    )
+    admin_password = getattr(args, "admin_password", None) or os.environ.get(
+        "MATOMO_ADMIN_PASSWORD"
+    )
+    admin_email = getattr(args, "admin_email", None) or os.environ.get(
+        "MATOMO_ADMIN_EMAIL"
+    )
+
+    token_description = (
+        getattr(args, "token_description", None)
+        or os.environ.get("MATOMO_TOKEN_DESCRIPTION")
+        or "matomo-bootstrap"
+    )
+
+    timeout = int(
+        getattr(args, "timeout", None) or os.environ.get("MATOMO_TIMEOUT") or "20"
+    )
+    debug = bool(getattr(args, "debug", False))
+
+    matomo_container_name = (
+        getattr(args, "matomo_container_name", None)
+        or os.environ.get("MATOMO_CONTAINER_NAME")
+        or None
+    )
+
+    missing: list[str] = []
+    if not base_url:
+        missing.append("--base-url (or MATOMO_URL)")
+    if not admin_user:
+        missing.append("--admin-user (or MATOMO_ADMIN_USER)")
+    if not admin_password:
+        missing.append("--admin-password (or MATOMO_ADMIN_PASSWORD)")
+    if not admin_email:
+        missing.append("--admin-email (or MATOMO_ADMIN_EMAIL)")
+
+    if missing:
+        raise ValueError("missing required values: " + ", ".join(missing))
+
+    return Config(
+        base_url=str(base_url),
+        admin_user=str(admin_user),
+        admin_password=str(admin_password),
+        admin_email=str(admin_email),
+        token_description=str(token_description),
+        timeout=timeout,
+        debug=debug,
+        matomo_container_name=matomo_container_name,
+    )

matomo_bootstrap-1.0.0/src/matomo_bootstrap/errors.py

@@ -0,0 +1,10 @@
+class BootstrapError(RuntimeError):
+    """Base error for matomo-bootstrap."""
+
+
+class MatomoNotReadyError(BootstrapError):
+    """Matomo is not reachable or not initialized."""
+
+
+class TokenCreationError(BootstrapError):
+    """Failed to create API token."""

matomo_bootstrap-1.0.0/src/matomo_bootstrap/health.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import urllib.request
+
+from .errors import MatomoNotReadyError
+
+
+def assert_matomo_ready(base_url: str, timeout: int = 10) -> None:
+    try:
+        with urllib.request.urlopen(base_url, timeout=timeout) as resp:
+            html = resp.read().decode("utf-8", errors="replace")
+    except Exception as exc:
+        raise MatomoNotReadyError(f"Matomo not reachable: {exc}") from exc
+
+    lower = html.lower()
+    if "matomo" not in lower and "piwik" not in lower:
+        raise MatomoNotReadyError("Matomo UI not detected at base URL")

matomo_bootstrap-1.0.0/src/matomo_bootstrap/http.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import http.cookiejar
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Dict, Tuple
+
+
+class HttpClient:
+    def __init__(self, base_url: str, timeout: int = 20, debug: bool = False):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.debug = debug
+
+        self.cookies = http.cookiejar.CookieJar()
+        self.opener = urllib.request.build_opener(
+            urllib.request.HTTPCookieProcessor(self.cookies)
+        )
+
+    def _dbg(self, msg: str) -> None:
+        if self.debug:
+            print(msg, file=sys.stderr)
+
+    def _open(self, req: urllib.request.Request) -> Tuple[int, str]:
+        try:
+            with self.opener.open(req, timeout=self.timeout) as resp:
+                body = resp.read().decode("utf-8", errors="replace")
+                return resp.status, body
+        except urllib.error.HTTPError as exc:
+            # urllib raises HTTPError for 4xx/5xx but it still contains status + body
+            try:
+                body = exc.read().decode("utf-8", errors="replace")
+            except Exception:
+                body = str(exc)
+            return exc.code, body
+
+    def get(self, path: str, params: Dict[str, str]) -> Tuple[int, str]:
+        qs = urllib.parse.urlencode(params)
+        if path == "/":
+            url = f"{self.base_url}/"
+        else:
+            url = f"{self.base_url}{path}"
+        if qs:
+            url = f"{url}?{qs}"
+
+        self._dbg(f"[HTTP] GET {url}")
+
+        req = urllib.request.Request(url, method="GET")
+        return self._open(req)
+
+    def post(self, path: str, data: Dict[str, str]) -> Tuple[int, str]:
+        url = self.base_url + path
+        encoded = urllib.parse.urlencode(data).encode()
+
+        self._dbg(f"[HTTP] POST {url} keys={list(data.keys())}")
+
+        req = urllib.request.Request(url, data=encoded, method="POST")
+        return self._open(req)

matomo_bootstrap-1.0.0/src/matomo_bootstrap/installers/__init__.py

@@ -0,0 +1 @@
+__all__ = []

matomo_bootstrap-1.0.0/src/matomo_bootstrap/installers/base.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..config import Config
+
+
+class Installer(ABC):
+    @abstractmethod
+    def ensure_installed(self, config: Config) -> None:
+        raise NotImplementedError

matomo_bootstrap-1.0.0/src/matomo_bootstrap/installers/web.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+from .base import Installer
+from ..config import Config
+
+
+# Optional knobs (mostly for debugging / CI stability)
+PLAYWRIGHT_HEADLESS = os.environ.get("MATOMO_PLAYWRIGHT_HEADLESS", "1").strip() not in (
+    "0",
+    "false",
+    "False",
+)
+PLAYWRIGHT_SLOWMO_MS = int(os.environ.get("MATOMO_PLAYWRIGHT_SLOWMO_MS", "0"))
+PLAYWRIGHT_NAV_TIMEOUT_MS = int(
+    os.environ.get("MATOMO_PLAYWRIGHT_NAV_TIMEOUT_MS", "60000")
+)
+
+# Values used by the installer flow (recorded)
+DEFAULT_SITE_NAME = os.environ.get("MATOMO_SITE_NAME", "localhost")
+DEFAULT_SITE_URL = os.environ.get("MATOMO_SITE_URL", "http://localhost")
+DEFAULT_TIMEZONE = os.environ.get("MATOMO_TIMEZONE", "Germany - Berlin")
+DEFAULT_ECOMMERCE = os.environ.get("MATOMO_ECOMMERCE", "Ecommerce enabled")
+
+
+def _log(msg: str) -> None:
+    # IMPORTANT: logs must not pollute stdout (tests expect only token on stdout)
+    print(msg, file=sys.stderr)
+
+
+def wait_http(url: str, timeout: int = 180) -> None:
+    """
+    Consider Matomo 'reachable' as soon as the HTTP server answers - even with 500.
+    urllib raises HTTPError for 4xx/5xx, so we must treat that as reachability too.
+    """
+    _log(f"[install] Waiting for Matomo HTTP at {url} ...")
+    last_err: Exception | None = None
+
+    for i in range(timeout):
+        try:
+            with urllib.request.urlopen(url, timeout=2) as resp:
+                _ = resp.read(128)
+            _log("[install] Matomo HTTP reachable (2xx/3xx).")
+            return
+        except urllib.error.HTTPError as exc:
+            _log(f"[install] Matomo HTTP reachable (HTTP {exc.code}).")
+            return
+        except Exception as exc:
+            last_err = exc
+            if i % 5 == 0:
+                _log(
+                    f"[install] still waiting ({i}/{timeout}) … ({type(exc).__name__})"
+                )
+            time.sleep(1)
+
+    raise RuntimeError(
+        f"Matomo did not become reachable after {timeout}s: {url} ({last_err})"
+    )
+
+
+def is_installed(url: str) -> bool:
+    """
+    Heuristic:
+    - installed instances typically render login module links
+    - installer renders 'installation' wizard content
+    """
+    try:
+        with urllib.request.urlopen(url, timeout=5) as resp:
+            html = resp.read().decode(errors="ignore").lower()
+        return (
+            ("module=login" in html)
+            or ("matomo › login" in html)
+            or ("matomo/login" in html)
+        )
+    except urllib.error.HTTPError as exc:
+        try:
+            html = exc.read().decode(errors="ignore").lower()
+            return (
+                ("module=login" in html)
+                or ("matomo › login" in html)
+                or ("matomo/login" in html)
+            )
+        except Exception:
+            return False
+    except Exception:
+        return False
+
+
+class WebInstaller(Installer):
+    def ensure_installed(self, config: Config) -> None:
+        """
+        Ensure Matomo is installed. NO-OP if already installed.
+        Uses Playwright to drive the web installer (recorded flow).
+        """
+        base_url = config.base_url
+
+        wait_http(base_url)
+
+        if is_installed(base_url):
+            if config.debug:
+                _log("[install] Matomo already looks installed. Skipping installer.")
+            return
+
+        from playwright.sync_api import sync_playwright
+
+        _log("[install] Running Matomo web installer via Playwright (recorded flow)...")
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(
+                headless=PLAYWRIGHT_HEADLESS,
+                slow_mo=PLAYWRIGHT_SLOWMO_MS if PLAYWRIGHT_SLOWMO_MS > 0 else None,
+            )
+            context = browser.new_context()
+            page = context.new_page()
+            page.set_default_navigation_timeout(PLAYWRIGHT_NAV_TIMEOUT_MS)
+            page.set_default_timeout(PLAYWRIGHT_NAV_TIMEOUT_MS)
+
+            def _dbg(msg: str) -> None:
+                if config.debug:
+                    _log(f"[install] {msg}")
+
+            def click_next() -> None:
+                """
+                Matomo installer mixes link/button variants and sometimes includes '»'.
+                We try common variants in a robust order.
+                """
+                candidates = [
+                    ("link", "Next »"),
+                    ("button", "Next »"),
+                    ("link", "Next"),
+                    ("button", "Next"),
+                    ("link", "Continue"),
+                    ("button", "Continue"),
+                    ("link", "Proceed"),
+                    ("button", "Proceed"),
+                    ("link", "Start Installation"),
+                    ("button", "Start Installation"),
+                    ("link", "Weiter"),
+                    ("button", "Weiter"),
+                    ("link", "Fortfahren"),
+                    ("button", "Fortfahren"),
+                ]
+
+                for role, name in candidates:
+                    loc = page.get_by_role(role, name=name)
+                    if loc.count() > 0:
+                        _dbg(f"click_next(): {role} '{name}'")
+                        loc.first.click()
+                        return
+
+                loc = page.get_by_text("Next", exact=False)
+                if loc.count() > 0:
+                    _dbg("click_next(): fallback text 'Next'")
+                    loc.first.click()
+                    return
+
+                raise RuntimeError(
+                    "Could not find a Next/Continue control in the installer UI."
+                )
+
+            page.goto(base_url, wait_until="domcontentloaded")
+
+            def superuser_form_visible() -> bool:
+                return page.locator("#login-0").count() > 0
+
+            for _ in range(12):
+                if superuser_form_visible():
+                    break
+                click_next()
+                page.wait_for_load_state("domcontentloaded")
+                page.wait_for_timeout(200)
+            else:
+                raise RuntimeError(
+                    "Installer did not reach superuser step (login-0 not found)."
+                )
+
+            page.locator("#login-0").click()
+            page.locator("#login-0").fill(config.admin_user)
+
+            page.locator("#password-0").click()
+            page.locator("#password-0").fill(config.admin_password)
+
+            if page.locator("#password_bis-0").count() > 0:
+                page.locator("#password_bis-0").click()
+                page.locator("#password_bis-0").fill(config.admin_password)
+
+            page.locator("#email-0").click()
+            page.locator("#email-0").fill(config.admin_email)
+
+            if page.get_by_role("button", name="Next »").count() > 0:
+                page.get_by_role("button", name="Next »").click()
+            else:
+                click_next()
+
+            if page.locator("#siteName-0").count() > 0:
+                page.locator("#siteName-0").click()
+                page.locator("#siteName-0").fill(DEFAULT_SITE_NAME)
+
+            if page.locator("#url-0").count() > 0:
+                page.locator("#url-0").click()
+                page.locator("#url-0").fill(DEFAULT_SITE_URL)
+
+            try:
+                page.get_by_role("combobox").first.click()
+                page.get_by_role("listbox").get_by_text(DEFAULT_TIMEZONE).click()
+            except Exception:
+                _dbg("Timezone selection skipped (not found / changed UI).")
+
+            try:
+                page.get_by_role("combobox").nth(2).click()
+                page.get_by_role("listbox").get_by_text(DEFAULT_ECOMMERCE).click()
+            except Exception:
+                _dbg("Ecommerce selection skipped (not found / changed UI).")
+
+            click_next()
+            page.wait_for_load_state("domcontentloaded")
+
+            if page.get_by_role("link", name="Next »").count() > 0:
+                page.get_by_role("link", name="Next »").click()
+
+            if page.get_by_role("button", name="Continue to Matomo »").count() > 0:
+                page.get_by_role("button", name="Continue to Matomo »").click()
+
+            context.close()
+            browser.close()
+
+        time.sleep(1)
+        if not is_installed(base_url):
+            raise RuntimeError("[install] Installer did not reach installed state.")
+
+        _log("[install] Installation finished.")

matomo_bootstrap-1.0.0/src/matomo_bootstrap/matomo_api.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import urllib.error
+
+from .errors import MatomoNotReadyError, TokenCreationError
+from .http import HttpClient
+
+
+def _md5(text: str) -> str:
+    return hashlib.md5(text.encode("utf-8")).hexdigest()
+
+
+def _try_json(body: str) -> object:
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise TokenCreationError(f"Invalid JSON from Matomo API: {body[:400]}") from exc
+
+
+def _dbg(msg: str, enabled: bool) -> None:
+    if enabled:
+        # Keep stdout clean (tests expect only token on stdout).
+        print(msg, file=sys.stderr)
+
+
+class MatomoApi:
+    def __init__(self, *, client: HttpClient, debug: bool = False):
+        self.client = client
+        self.debug = debug
+
+    def assert_ready(self, timeout: int = 10) -> None:
+        """
+        Minimal readiness check: Matomo UI should be reachable and look like Matomo.
+        """
+        try:
+            status, body = self.client.get("/", {})
+        except Exception as exc:  # pragma: no cover
+            raise MatomoNotReadyError(f"Matomo not reachable: {exc}") from exc
+
+        _dbg(f"[ready] GET / -> HTTP {status}", self.debug)
+
+        html = (body or "").lower()
+        if "matomo" not in html and "piwik" not in html:
+            raise MatomoNotReadyError("Matomo UI not detected at base URL")
+
+    def login_via_logme(self, admin_user: str, admin_password: str) -> None:
+        """
+        Create an authenticated Matomo session (cookie jar) using Login controller.
+        Matomo accepts md5 hashed password in `password` parameter for action=logme.
+        """
+        md5_password = _md5(admin_password)
+        try:
+            status, body = self.client.get(
+                "/index.php",
+                {
+                    "module": "Login",
+                    "action": "logme",
+                    "login": admin_user,
+                    "password": md5_password,
+                },
+            )
+            _dbg(f"[auth] logme HTTP {status} body[:120]={body[:120]!r}", self.debug)
+        except urllib.error.HTTPError as exc:
+            # Even 4xx/5xx can still set cookies; continue and let the API call validate.
+            try:
+                err_body = exc.read().decode("utf-8", errors="replace")
+            except Exception:
+                err_body = ""
+            _dbg(
+                f"[auth] logme HTTPError {exc.code} body[:120]={err_body[:120]!r}",
+                self.debug,
+            )
+
+    def create_app_specific_token(
+        self,
+        *,
+        admin_user: str,
+        admin_password: str,
+        description: str,
+    ) -> str:
+        """
+        Create an app-specific token using an authenticated session (cookies),
+        not UsersManager.getTokenAuth (not available in Matomo 5.3.x images).
+        """
+        env_token = os.environ.get("MATOMO_BOOTSTRAP_TOKEN_AUTH")
+        if env_token:
+            _dbg(
+                "[auth] Using MATOMO_BOOTSTRAP_TOKEN_AUTH from environment.", self.debug
+            )
+            return env_token
+
+        self.login_via_logme(admin_user, admin_password)
+
+        status, body = self.client.post(
+            "/index.php",
+            {
+                "module": "API",
+                "method": "UsersManager.createAppSpecificTokenAuth",
+                "userLogin": admin_user,
+                "passwordConfirmation": admin_password,
+                "description": description,
+                "format": "json",
+            },
+        )
+
+        _dbg(
+            f"[auth] createAppSpecificTokenAuth HTTP {status} body[:200]={body[:200]!r}",
+            self.debug,
+        )
+
+        if status != 200:
+            raise TokenCreationError(
+                f"HTTP {status} during token creation: {body[:400]}"
+            )
+
+        data = _try_json(body)
+        token = data.get("value") if isinstance(data, dict) else None
+        if not token:
+            raise TokenCreationError(f"Unexpected response from token creation: {data}")
+
+        return str(token)

matomo_bootstrap-1.0.0/src/matomo_bootstrap/service.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from .config import Config
+from .http import HttpClient
+from .matomo_api import MatomoApi
+from .installers.web import WebInstaller
+
+
+def run(config: Config) -> str:
+    """
+    Orchestrate:
+      1) Ensure Matomo is installed (NO-OP if installed)
+      2) Ensure Matomo is reachable/ready
+      3) Create an app-specific token using an authenticated session
+    """
+    installer = WebInstaller()
+    installer.ensure_installed(config)
+
+    client = HttpClient(
+        base_url=config.base_url,
+        timeout=config.timeout,
+        debug=config.debug,
+    )
+    api = MatomoApi(client=client, debug=config.debug)
+
+    api.assert_ready(timeout=config.timeout)
+
+    token = api.create_app_specific_token(
+        admin_user=config.admin_user,
+        admin_password=config.admin_password,
+        description=config.token_description,
+    )
+    return token

matomo_bootstrap-1.0.0/src/matomo_bootstrap.egg-info/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: matomo-bootstrap
+Version: 1.0.0
+Summary: Headless bootstrap tooling for Matomo (installation + API token provisioning)
+Author-email: Kevin Veen-Birkenbach <kevin@veen.world>
+License: MIT
+Project-URL: Homepage, https://github.com/kevinveenbirkenbach/matomo-bootstrap
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.40.0
+Provides-Extra: e2e
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# matomo-bootstrap
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+
+
+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:
+
+```bash
+nix run github:kevinveenbirkenbach/matomo-bootstrap
+```
+
+Install Playwright’s Chromium browser (one-time):
+
+```bash
+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**
+
+```bash
+pip install matomo-bootstrap
+```
+
+Install Chromium for Playwright:
+
+```bash
+python -m playwright install chromium
+```
+
+---
+
+## Usage
+
+### CLI
+
+```bash
+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:
+
+```text
+6c7a8c2b0e9e4a3c8e1d0c4e8a6b9f21
+```
+
+---
+
+### Environment Variables
+
+All options can be provided via environment variables:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+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/](https://www.veen.world/)
+
+---
+
+## License
+
+MIT License
+See [LICENSE](LICENSE)

matomo_bootstrap-1.0.0/src/matomo_bootstrap.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+src/matomo_bootstrap/__init__.py
+src/matomo_bootstrap/__main__.py
+src/matomo_bootstrap/cli.py
+src/matomo_bootstrap/config.py
+src/matomo_bootstrap/errors.py
+src/matomo_bootstrap/health.py
+src/matomo_bootstrap/http.py
+src/matomo_bootstrap/matomo_api.py
+src/matomo_bootstrap/service.py
+src/matomo_bootstrap.egg-info/PKG-INFO
+src/matomo_bootstrap.egg-info/SOURCES.txt
+src/matomo_bootstrap.egg-info/dependency_links.txt
+src/matomo_bootstrap.egg-info/entry_points.txt
+src/matomo_bootstrap.egg-info/requires.txt
+src/matomo_bootstrap.egg-info/top_level.txt
+src/matomo_bootstrap/installers/__init__.py
+src/matomo_bootstrap/installers/base.py
+src/matomo_bootstrap/installers/web.py

matomo_bootstrap-1.0.0/src/matomo_bootstrap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

matomo_bootstrap-1.0.0/src/matomo_bootstrap.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+matomo-bootstrap = matomo_bootstrap.__main__:main

matomo_bootstrap-1.0.0/src/matomo_bootstrap.egg-info/requires.txt

@@ -0,0 +1,6 @@
+playwright>=1.40.0
+
+[dev]
+ruff
+
+[e2e]

matomo_bootstrap-1.0.0/src/matomo_bootstrap.egg-info/top_level.txt

@@ -0,0 +1 @@
+matomo_bootstrap