vibecodeit

Build Umami Cloud

YESreplaces $20/mosaves $240/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 user-operated Umami installation with verified collection and restoration.

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

ApplicationUpstream Umami containerStoragePostgreSQLDeploymentDocker 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://docs.umami.is/docs/install, 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: A user-owned test site with two page loads and one signup-click custom event. 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 user-operated Umami installation with verified collection and restoration. 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 Umami PostgreSQL schema without custom tables. Persist the database, Compose configuration, selected image digest and encrypted deployment secrets. Track a test website id and a named proof event in OPERATIONS.md.
- Use stable ids and explicit relationships; add auxiliary tables named by the phases before those phases use them.
- Acceptance fixture: A user-owned test site with two page loads and one signup-click custom event.

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:3000The loopback URL selected in compose.yaml; replace with your HTTPS origin only after completing product deployment.
POSTGRES_PASSWORDsecretrequiredreplace-with-random-db-passwordGenerate a random password, map it into the database service and URL; keep it outside version control.
DATABASE_URLsecretrequiredpostgresql://umami:replace-password@db:5432/umamiCompose internal PostgreSQL connection URL; URL-encode special password characters.

The build, in order

  1. Deployment inventory and safe pilot

    Prepare the pinned upstream deployment for a user-operated Umami installation with verified collection and restoration.

    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 Umami PostgreSQL schema without custom tables. Persist the database, Compose configuration, selected image digest and encrypted deployment secrets. Track a test website id and a named proof event 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: A user-owned test site with two page loads and one signup-click custom event. 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. Isolated upstream deployment

    Isolated upstream deployment for Umami Cloud: Deploy the official Umami container with PostgreSQL on an internal Compose network and a loopback-only app port; pin tested image digests.

    1. Deploy the official Umami container with PostgreSQL on an internal Compose network and a loopback-only app port; pin tested image digests.

      Files compose.yamlOPERATIONS.md

    2. Set DATABASE_URL using the internal database service name and change the initial administrator password immediately.

      Files OPERATIONS.md

    3. Use A user-owned test site with two page loads and one signup-click custom event. Check: The dashboard opens locally and the original default password no longer works. Then check: Restarting both containers preserves the administrator and registered website. Record commands, observed results and the date in OPERATIONS.md.

      Files OPERATIONS.md

    done when · tick each as it passes
    watch out
    • Do not implement a second analytics engine or edit upstream database tables.
    next phase

  3. Prove collection

    Prove collection for Umami Cloud: Register the owned test website and use the exact tracking snippet generated by this installed version.

    1. Register the owned test website and use the exact tracking snippet generated by this installed version.

      Files compose.yamlOPERATIONS.md

    2. Generate the fixture pageviews and named event; inspect the network response and dashboard before declaring collection healthy.

      Files OPERATIONS.md

    3. Use A user-owned test site with two page loads and one signup-click custom event. Check: The named signup-click event appears for the correct website. Then check: No event is attributed to a second website id in the fixture. Record commands, observed results and the date in OPERATIONS.md.

      Files OPERATIONS.md

    done when · tick each as it passes
    watch out
    • Collection blocked by consent settings or a browser extension is not evidence that the server is down.
    next phase

  4. Restore and upgrade drill

    Restore and upgrade drill for Umami Cloud: Create a consistent PostgreSQL logical backup and record the matching app/database versions and secret recovery location.

    1. Create a consistent PostgreSQL logical backup and record the matching app/database versions and secret recovery location.

      Files compose.yamlOPERATIONS.md

    2. Restore into a separate Compose project with a new volume, compare websites/events and rehearse an upgrade there before production.

      Files OPERATIONS.md

    3. Use A user-owned test site with two page loads and one signup-click custom event. Check: The restored dashboard contains the test website and proof event. Then check: The restore exercise touches no live database volume and records its date. Record commands, observed results and the date in OPERATIONS.md.

      Files OPERATIONS.md

    done when · tick each as it passes
    watch out
    • Changing a database major version is a migration, not a routine image pull.
    next phase

  5. Portable delivery and clean-start proof

    Finish the Umami 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: Isolated upstream deployment; Prove collection; Restore and upgrade drill. 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. Use a PostgreSQL logical dump plus the Compose file, image manifest and securely stored deployment secrets. Restore into a separate empty directory or isolated deployment, with all outbound actions and schedules disabled. Recreate this proof: A user-owned test site with two page loads and one signup-click custom event. 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.