vibecodeit

Build Matomo Cloud

KINDAreplaces $26/mosaves $312/yrback to the verdict

0%0 of 19 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

Build a self-hosted Matomo installation with working archives and recoverable data.

estimated effort multi-daythe files for this build are in the project pack

ApplicationUpstream Matomo containerStorageUpstream-compatible MySQL/MariaDBDeploymentDocker Compose; Caddy for product HTTPS

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

  1. installDocker Engine has no hosting fee; Desktop licensing depends on your use, and a rented host is billed separately.

    Why The upstream application runs in containers.

    Get it Install Docker Engine and the Compose plugin on Linux using the official instructions. On Windows use Docker Desktop with WSL2, then work inside a Linux project folder. open ↗

    Verify docker compose version prints a v2 version and docker info reaches the daemon.

  2. decideSoftware/edition terms and optional paid features are defined by the upstream project.

    Why The guide must match the software you actually deploy.

    Get it Open https://matomo.org/faq/on-premise/installing-matomo/, choose a stable release compatible with its database requirements, record its tag and resolved digest in versions.txt, and use those values in compose.yaml. Avoid unattended latest-tag updates. open ↗

    Verify versions.txt names both application and database versions or states that the pilot uses embedded SQLite.

  3. have readyNo paid service required for this local step.

    Why This fixture makes the first end-to-end check reproducible.

    Get it Create synthetic sample data before implementation: One owned site with a pageview, a campaign-tagged visit and a goal completion. Save it under fixtures/ with the expected results in fixtures/README.md; use no real credentials or customer records.

    Verify The fixture files and expected outcomes exist and can be inspected without a vendor account.

  4. decideNo paid service required for this local step.

    Why The full commercial product is larger than this guide.

    Get it The deliverable is a self-hosted Matomo installation with working archives and recoverable data. Read every exclusion below. Indie mode runs locally; any public or shared use requires the product access and deployment gates first.

    Verify You can name the primary workflow and the vendor features this version deliberately leaves out.

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- Use the upstream Matomo MySQL/MariaDB schema. Back up its database, config/config.ini.php, custom plugin/theme files and the pinned application version together. Keep test site ids and archive-run evidence in OPERATIONS.md.
- Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them.
- Acceptance fixture: One owned site with a pageview, a campaign-tagged visit and a goal completion.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

VariableNeededExampleWhere the value comes from
APP_IMAGErequiredreplace-with-tested-image-and-digestCopy the exact application image reference selected from upstream into compose.yaml via this variable.
SITE_URLrequiredhttp://localhost:8080The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment.
DB_PASSWORDsecretrequiredreplace-with-random-db-passwordGenerate a dedicated database password and use it in the database service and Matomo installer; protect config/config.ini.php.

The build, in order

  1. Deployment inventory and safe pilot

    Prepare the pinned upstream deployment for a self-hosted Matomo installation with working archives and recoverable data.

    1. Read the linked upstream installation guide and create compose.yaml, .env.example, versions.txt and OPERATIONS.md. Map APP_IMAGE and only each service's required environment variables explicitly. Keep database ports internal and map the pilot application port to 127.0.0.1.

      Files compose.yaml.env.exampleversions.txt

    2. Use the upstream Matomo MySQL/MariaDB schema. Back up its database, config/config.ini.php, custom plugin/theme files and the pinned application version together. Keep test site ids and archive-run evidence in OPERATIONS.md. Name each volume and its mount path in OPERATIONS.md; never use ephemeral container storage for the only copy. Create .env manually from .env.example and replace placeholders before starting.

      Files OPERATIONS.md.gitignore

      terminal
      docker compose config --quiet

    3. Create a private fixtures/ folder containing: One owned site with a pageview, a campaign-tagged visit and a goal completion. Create a separate backup destination and an isolated restore-project name; do not reuse live volumes in restore exercises.

      Files fixtures/README.mdOPERATIONS.md

    done when · tick each as it passes
    watch out
    • A valid Compose file proves configuration syntax only, not application health.
    next phase

  2. Install existing analytics

    Install existing analytics for Matomo Cloud: Deploy the official Matomo PHP application and a compatible database from the upstream install requirements; bind the app to loopback initially.

    1. Deploy the official Matomo PHP application and a compatible database from the upstream install requirements; bind the app to loopback initially.

      Files compose.yamlOPERATIONS.md

    2. Complete the installer, create the admin and test site and record system-check results before adding tracking.

      Files OPERATIONS.md

    3. Use One owned site with a pageview, a campaign-tagged visit and a goal completion. Check: The installer system checks pass and the dashboard opens with the new admin. Then check: A container restart preserves the site configuration and account. Record commands, observed results and the date in OPERATIONS.md.

      Files OPERATIONS.md

    done when · tick each as it passes
    watch out
    • The task is operating Matomo, not cloning its tracking pipeline.
    next phase

  3. Collection and archiving

    Collection and archiving for Matomo Cloud: Install the generated tracker on the owned site and configure privacy/retention settings intentionally.

    1. Install the generated tracker on the owned site and configure privacy/retention settings intentionally.

      Files compose.yamlOPERATIONS.md

    2. Run the upstream console archive task, schedule it with the documented URL and inspect its exit status and log age.

      Files OPERATIONS.md

    3. Use One owned site with a pageview, a campaign-tagged visit and a goal completion. Check: The campaign visit and configured goal appear after a successful archive run. Then check: Breaking database access makes archiving fail visibly instead of updating a false success timestamp. Record commands, observed results and the date in OPERATIONS.md.

      Files OPERATIONS.md

    done when · tick each as it passes
    watch out
    • A collecting tracker can coexist with stale reports when the archive job is broken.
    next phase

  4. Complete backup and restore

    Complete backup and restore for Matomo Cloud: Back up the database plus config and custom files as one dated set; encrypt it off-host and keep a manifest.

    1. Back up the database plus config and custom files as one dated set; encrypt it off-host and keep a manifest.

      Files compose.yamlOPERATIONS.md

    2. Restore to an isolated installation with outbound tracking disabled and verify the site, goal and reports before planning an update.

      Files OPERATIONS.md

    3. Use One owned site with a pageview, a campaign-tagged visit and a goal completion. Check: The restored instance contains the fixture goal and site settings. Then check: Restoring only the database is documented as incomplete because configuration and custom files also matter. Record commands, observed results and the date in OPERATIONS.md.

      Files OPERATIONS.md

    done when · tick each as it passes
    watch out
    • Premium plugins and vendor-operated infrastructure are separate from the self-hosted core.
    next phase

  5. Portable delivery and clean-start proof

    Finish the Matomo Cloud replacement with a documented first-run path and a recoverable export.

    1. Document prerequisites, every configuration variable, data locations and the three domain workflows: Install existing analytics; Collection and archiving; Complete backup and restore. Include the exclusions, actual costs and source check date 2026-09-05. Commands shown earlier that reference project files are files the builder must implement before running them.

      Files README.md.env.example

    2. Create a consistent database dump plus config/config.ini.php, the pinned Matomo version and custom files. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: One owned site with a pageview, a campaign-tagged visit and a goal completion. Compare ids/counts and open the result before recording the restore date. Never test a restore over the only live copy.

      Files OPERATIONS.mdbackup/README.md

    3. Use a new folder and only README instructions to reach the fixture outcome. Verify upstream login, persistence, proof output and restore. Record exactly what passed; do not mark unrun checks complete.

      Files README.mdverification.md

      terminal
      docker compose ps
    done when · tick each as it passes
    watch out
    • Export without an import or restore rehearsal is not verified portability.
what this build does not replace
after v1, if you want it

Need the files? The project pack on the verdict page hands your agent the whole brief · more analytics.