From 50914dea8b0b504b695868643fb8d07b7b1dc4aa Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Tue, 23 Dec 2025 13:02:33 +0100
Subject: [PATCH] docs(readme): add installation and usage instructions for nix
 and python

Document how to install and use matomo-bootstrap via Nix flakes and pip,
describe CLI usage, environment variables, debug mode, E2E workflow,
and add author attribution.

https://chatgpt.com/share/694a84dd-aa30-800f-b45e-8a30e66e1c9b
---
 README.md | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 177 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2584717..dacc293 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,181 @@
 # matomo-bootstrap
 
-Homepage: https://github.com/kevinveenbirkenbach/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:
+
+```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 <kevin@veen.world>
+
+**Kevin Veen-Birkenbach**
+🌐 [https://www.veen.world/](https://www.veen.world/)
+
+---
+
+## License
+
+MIT License
+See [LICENSE](LICENSE)