# AGENTS.md — Build guide for Umami Cloud

## Project scope
Deploy the official Umami application with PostgreSQL and HTTPS, replace default credentials and register a site using its documented tracker. Add a scheduled consistent backup and an isolated restore workflow.

Catalogue verdict: yes. The software is open source, so the cloud subscription is mostly paying for managed hosting, upgrades, and not touching a server.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing.
- Implementation components: Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes. Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore.
- Scope boundary: Managed hosting, upgrade support and compliance assurances are not included.

## Stack and architecture
- Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes.
- Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore.
- Operating records: pinned official Umami image, PostgreSQL database, site registrations, environment configuration and backup history

## Security and data integrity
- Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository.
- Correctness boundary: Do not reimplement the tracker or invent upstream environment variables; database credentials and administrator sessions remain private.
- Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.
- Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point.

## Agent implementation rules
- Project rule — operating records: pinned official Umami image, PostgreSQL database, site registrations, environment configuration and backup history
- Project rule — preserve this invariant: Do not reimplement the tracker or invent upstream environment variables; database credentials and administrator sessions remain private.
- Project rule — acceptance evidence: A staging tracker event appears for the configured site; a restored database retains sites and historical reports without exposing admin access.

## Optional agent skills and references
- Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate the actual Umami Cloud-inspired workflow with owned or clearly labeled sample data: Deploy the official Umami application with PostgreSQL and HTTPS, replace default credentials and register a site using its documented tracker. Add a scheduled consistent backup and an isolated restore workflow.
- Publish a reproducible walkthrough with this observable result: A staging tracker event appears for the configured site; a restored database retains sites and historical reports without exposing admin access.
- Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: Managed hosting, upgrade support and compliance assurances are not included. Avoid guaranteed savings, performance scores or implied endorsement.

## Engineering roadmap
1. Phase 1 — Select and document the upstream release. Deploy the official Umami application with PostgreSQL and HTTPS, replace default credentials and register a site using its documented tracker. Add a scheduled consistent backup and an isolated restore workflow. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Managed hosting, upgrade support and compliance assurances are not included.
2. Phase 2 — Configure the maintained application. Record pinned official Umami image, PostgreSQL database, site registrations, environment configuration and backup history Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Do not reimplement the tracker or invent upstream environment variables; database credentials and administrator sessions remain private.
3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.
4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate.
5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files.
6. Phase 6 — Operator handoff and acceptance. A staging tracker event appears for the configured site; a restored database retains sites and historical reports without exposing admin access. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting.

## Paid-product capabilities outside this build
- managed hosting
- upgrades
- reliability
- team/billing convenience
- support

## Implementation prompt
WORKING SLICE
Deploy the official Umami application with PostgreSQL and HTTPS, replace default credentials and register a site using its documented tracker. Add a scheduled consistent backup and an isolated restore workflow.

Operate this scoped Umami Cloud-inspired deployment through the maintained upstream application. Record its configuration and failure states; do not rebuild its schema, interface or services.

Architecture
- Docker Compose around the selected upstream application, pinned release/image digest and persistent volumes.
- Caddy for HTTPS, environment templates without secrets, and operator scripts for backups, upgrades and restore.

Prerequisites and limits
A user-owned Linux server, domain/DNS control, sufficient disk and memory, and the selected upstream release documentation. Record actual image names and required variables rather than guessing.
Outside this release: Managed hosting, upgrade support and compliance assurances are not included.

Configuration and correctness
pinned official Umami image, PostgreSQL database, site registrations, environment configuration and backup history
Invariant: Do not reimplement the tracker or invent upstream environment variables; database credentials and administrator sessions remain private.
Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.

Security and privacy
Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository.

Recovery and export
Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point.

Implementation order
1. Phase 1 — Select and document the upstream release. Deploy the official Umami application with PostgreSQL and HTTPS, replace default credentials and register a site using its documented tracker. Add a scheduled consistent backup and an isolated restore workflow. Record the release, documented host requirements and upstream deployment reference. Start in an isolated staging directory. Keep these exclusions explicit: Managed hosting, upgrade support and compliance assurances are not included.
2. Phase 2 — Configure the maintained application. Record pinned official Umami image, PostgreSQL database, site registrations, environment configuration and backup history Configure supported environment variables, credentials, volumes and database connections. Use upstream installation and migration procedures; do not create a replacement application schema, authentication service or dashboard. Preserve this rule: Do not reimplement the tracker or invent upstream environment variables; database credentials and administrator sessions remain private.
3. Phase 3 — Use the upstream workflow. Perform the stated workflow through the upstream interface or its documented CLI. Add an operator helper script only when the working slice explicitly calls for it; do not build a new input/review/output frontend. Back up before each upgrade, retain the previous image and configuration, and check upstream schema migration notes; a container rollback alone may not reverse a database migration.
4. Phase 4 — Review access and failure states. Generate unique administrator secrets, restrict exposed ports and disable public signup if the deployment is private. Keep backups encrypted and credentials outside the repository. Document health checks, reconnect/restart steps and how missing configuration is surfaced by the upstream service. Keep public and administrative endpoints separate.
5. Phase 5 — Recovery and upgrades. Capture the complete database and persistent file set consistently. Rehearse recovery into separate volumes and document the supported rollback point. Document upstream migration compatibility before an upgrade, the retained rollback point and the sequence for restoring configuration, data and files.
6. Phase 6 — Operator handoff and acceptance. A staging tracker event appears for the configured site; a restored database retains sites and historical reports without exposing admin access. Record actual staging observations separately from these proposed checks. Deliver the pinned configuration, secret-free environment template, backup/restore runbook and any explicitly scoped helper scripts; do not claim equivalence to managed hosting.

Acceptance
A staging tracker event appears for the configured site; a restored database retains sites and historical reports without exposing admin access.
Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees.

Optional agent guidance
Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [agent-browser](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) — Automate browser interaction using accessibility snapshots, element references and reproducible navigation workflows. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Project rule — operating records: pinned official Umami image, PostgreSQL database, site registrations, environment configuration and backup history
Project rule — preserve this invariant: Do not reimplement the tracker or invent upstream environment variables; database credentials and administrator sessions remain private.
Project rule — acceptance evidence: A staging tracker event appears for the configured site; a restored database retains sites and historical reports without exposing admin access.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.