{ "schema_version": "0.5.0", "kind": "proxmenux.oci-template", "id": "image-umami", "status": "generated-unvalidated", "catalog_ui": { "title": { "en_US": "Umami" }, "tagline": { "en_US": "Privacy-focused, self-hosted web analytics." }, "description": { "en_US": "Umami is a privacy-focused web analytics platform. This recipe uses the official Umami image with a separate PostgreSQL LXC for persistent analytics data." }, "category": "monitoring", "category_label": "Monitoring & Analytics", "author": "Umami Software", "developer": "Umami Software", "icon": "https://cdn.jsdelivr.net/gh/selfhst/icons@main/webp/umami.webp", "thumbnail": null, "screenshots": [], "architectures": [ "amd64", "arm64" ], "launch": { "scheme": "http", "port": 3000, "path": "/" }, "website": "https://umami.is/", "documentation": "https://docs.umami.is/docs/install", "repository": "https://github.com/umami-software/umami", "tips": [ "The initial administrator login is admin / umami. Change the password immediately after the first sign-in.", "Umami runs in one LXC and PostgreSQL in a separate private LXC. The PostgreSQL managed volume stores analytics data; the Umami service has no data volume.", "The official Compose healthcheck probes /api/heartbeat. ProxMenux performs its standard first-start HTTP check against the web root; verify /api/heartbeat and sign-in separately during runtime validation.", "The Compose file uses official Umami and PostgreSQL images. ProxMenux generates a unique database password, APP_SECRET, and 64-character TWO_FACTOR_ENCRYPTION_KEY." ], "mini_changelog": [], "display_version": null, "updated_at": "2026-10-23" }, "source": { "provider": "umami", "repository": "https://github.com/umami-software/umami", "default_branch": "master", "revision": "559e3c607c23d2c72d9bd4f6481bda428255323c", "image_repository_url": "https://github.com/umami-software/umami/pkgs/container/umami", "readme_pushed_at": "", "compose_sha256": "fb542a641c14fc2b1ff0d59558a197ed4f607b6608bf812afd20dad662ae0e8c", "generated_at": "2026-10-27T09:38:05+00:00", "readme_raw_url": "https://raw.githubusercontent.com/umami-software/umami/559e3c607c23d2c72d9bd4f6481bda428255323c/docker-compose.yml" }, "container_contract": { "service_name": "umami", "container_name": "umami", "image": { "reference": "ghcr.io/umami-software/umami:latest", "registry": "ghcr.io", "repository": "ghcr.io/umami-software/umami", "tag": "latest", "digest": null, "pull_policy": "resolve-selected-tag-to-architecture-digest-at-install" }, "environment": [ { "name": "DATABASE_URL", "example": "postgresql://umami:${GENERATED_DB_PASSWORD}@db:5432/umami", "required": true, "sensitive": true, "source": "official-docker-compose" }, { "name": "APP_SECRET", "example": "${GENERATED_APP_SECRET}", "required": true, "sensitive": true, "source": "official-documentation" }, { "name": "TWO_FACTOR_ENCRYPTION_KEY", "example": "${GENERATED_TWO_FACTOR_ENCRYPTION_KEY}", "required": true, "sensitive": true, "source": "official-docker-compose" } ], "volumes": [], "ports": [ { "container_port": 3000, "published_example": 3000, "protocol": "tcp", "required": true, "proxmox_behavior": "listener-on-dedicated-lxc-address-no-nat" } ], "related_services": [ { "name": "db", "image": "postgres:15-alpine" } ], "restart": "always", "stop_grace_period": null, "original_compose": "---\nservices:\n umami:\n image: ghcr.io/umami-software/umami:latest\n ports:\n - \"3000:3000\"\n environment:\n DATABASE_URL: postgresql://umami:umami@db:5432/umami\n APP_SECRET: replace-me-with-a-random-string\n # Required for two-factor authentication, generate with: openssl rand -hex 32\n TWO_FACTOR_ENCRYPTION_KEY: replace-me-with-a-64-character-hex-string\n depends_on:\n db:\n condition: service_healthy\n init: true\n restart: always\n healthcheck:\n test: [\"CMD-SHELL\", \"curl http://localhost:3000/api/heartbeat\"]\n interval: 5s\n timeout: 5s\n retries: 5\n db:\n image: postgres:15-alpine\n environment:\n POSTGRES_DB: umami\n POSTGRES_USER: umami\n POSTGRES_PASSWORD: umami\n volumes:\n - umami-db-data:/var/lib/postgresql/data\n restart: always\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}\"]\n interval: 5s\n timeout: 5s\n retries: 5\nvolumes:\n umami-db-data:\n" }, "compose_stack": { "project_name": "umami", "deployment_model": "one-native-oci-lxc-per-compose-service", "user_experience": "single-application-install", "main_service": "umami", "service_count": 2, "services": [ { "name": "db", "image": "postgres:15-alpine", "is_main": false, "role": "dependency", "vmid_offset": 1, "depends_on": [], "frontend_network": false, "private_network": true, "compose": { "image": "postgres:15-alpine", "environment": { "POSTGRES_DB": "umami", "POSTGRES_USER": "umami", "POSTGRES_PASSWORD": "${GENERATED_DB_PASSWORD}" }, "volumes": [ "umami-db-data:/var/lib/postgresql/data" ], "restart": "always", "healthcheck": { "test": [ "CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}" ], "interval": "5s", "timeout": "5s", "retries": 5 } } }, { "name": "umami", "image": "ghcr.io/umami-software/umami:latest", "is_main": true, "role": "frontend", "vmid_offset": 0, "depends_on": [ "db" ], "frontend_network": true, "private_network": true, "compose": { "image": "ghcr.io/umami-software/umami:latest", "ports": [ "3000:3000" ], "environment": { "DATABASE_URL": "postgresql://umami:${GENERATED_DB_PASSWORD}@db:5432/umami", "APP_SECRET": "${GENERATED_APP_SECRET}", "TWO_FACTOR_ENCRYPTION_KEY": "${GENERATED_TWO_FACTOR_ENCRYPTION_KEY}" }, "depends_on": { "db": { "condition": "service_healthy" } }, "init": true, "restart": "always", "healthcheck": { "test": [ "CMD-SHELL", "curl http://localhost:3000/api/heartbeat" ], "interval": "5s", "timeout": "5s", "retries": 5 } } } ], "top_level": { "name": "umami", "volumes": { "umami-db-data": {} } }, "networking": { "frontend": "selected-proxmox-bridge", "private_required": true, "private_creation": "automatic-create-if-missing", "private_address_allocation": "automatic-static-address-per-service", "service_discovery": "private-addresses-replace-compose-service-dns", "dependency_external_access": "disabled", "prompt_user_for_private_network": false }, "storage": [ { "id": "umami-database-data", "service": "db", "container_path": "/var/lib/postgresql/data", "mode": "managed-volume", "user_selectable": true, "backup": true, "shared_with_other_lxc": false, "default": "managed-volume", "installation_choice": [ "managed-volume", "host-bind" ] } ], "orchestration": { "reserve_vmids_atomically": 2, "start_order": [ "db", "umami" ], "stop_order": [ "umami", "db" ], "dependency_readiness": "postgres-healthcheck-before-application", "rollback_on_failure": "preserve-created-containers-and-volumes-for-diagnosis" }, "installer_inputs": { "prompted": [ "stack_name", "base_vmid", "rootfs_storage", "persistent_data_destinations", "frontend_bridge", "frontend_ipv4_mode" ], "automatic": [ "dependent_vmids", "private_bridge", "private_subnet", "private_service_addresses", "compose_service_aliases", "generated_secrets", "dependency_start_and_stop_order" ], "generated_secrets": [ { "id": "db-password", "strategy": "generate-cryptographically-random-at-install", "bindings": [ { "service": "db", "environment_variable": "POSTGRES_PASSWORD" }, { "service": "umami", "environment_variable": "DATABASE_URL" } ] }, { "id": "app-secret", "strategy": "generate-cryptographically-random-at-install", "bindings": [ { "service": "umami", "environment_variable": "APP_SECRET" } ] }, { "id": "two-factor-encryption-key", "strategy": "generate-cryptographically-random-at-install", "bindings": [ { "service": "umami", "environment_variable": "TWO_FACTOR_ENCRYPTION_KEY" } ] } ] } }, "first_run": { "endpoints": [ { "label": "Web UI", "scheme": "http", "port": 3000, "path": "/", "source": "official-docker-compose" } ], "credentials": [ { "label": "Initial Umami administrator", "type": "static-default", "username": "admin", "password": "umami", "change_required": true, "source": "official-documentation", "retrieval": null } ] }, "proxmox": { "runtime": "native-oci-lxc", "technology_status": "proxmox-technology-preview", "defaults": { "unprivileged": true, "ostype": "auto-from-image", "cores": 2, "memory_mb": 1024, "swap_mb": 512, "rootfs_size_gb": 8, "rootfs_storage": "local-zfs", "volume_storage": "local-zfs", "template_storage": "local", "bridge": "vmbr0", "ipv4": "dhcp", "firewall": true, "host_managed_network": true, "onboot": false, "features": [ "nesting=1" ], "shutdown_timeout_seconds": 60 }, "image_metadata_policy": { "entrypoint": "import-from-oci-image", "cmd": "import-from-oci-image", "environment": "import-image-env-then-apply-compose-overrides", "user": "import-from-oci-image", "working_dir": "import-from-oci-image", "stop_signal": "import-from-oci-image" }, "adaptations": [ { "id": "compose-dependency-network", "upstream_behavior": "Docker Compose resolves the db service name on the project network and waits until PostgreSQL is healthy.", "native_lxc_behavior": "ProxMenux creates a private Proxmox bridge, gives each service its own LXC, maps the db alias, and waits for PostgreSQL readiness before first starting Umami.", "reason": "The two official Compose services run in separate native OCI LXCs.", "behavioral_impact": "PostgreSQL stays on the private service network and has no published port.", "validation": "passed" }, { "id": "generated-compose-secrets", "upstream_behavior": "The official Compose file uses example values for APP_SECRET, TWO_FACTOR_ENCRYPTION_KEY, and PostgreSQL credentials.", "native_lxc_behavior": "ProxMenux generates a unique PostgreSQL password, APP_SECRET, and a 64-character hexadecimal two-factor key for each installation.", "reason": "Do not reuse example credentials between installations.", "behavioral_impact": "The administrator still changes Umami’s documented initial admin password after first sign-in.", "validation": "passed" }, { "id": "compose-healthcheck", "upstream_behavior": "The official Compose file probes /api/heartbeat every five seconds for Umami and uses pg_isready for PostgreSQL.", "native_lxc_behavior": "The stack waits for PostgreSQL readiness, then ProxMenux performs its standard first-start HTTP check at the Umami web root. It does not install a continuous health monitor.", "reason": "The current generic installer uses the application endpoint for its first-start check.", "behavioral_impact": "Runtime validation should separately check /api/heartbeat and the interactive login.", "validation": "passed" } ], "installer_profile": { "stack_driver": "generic-multi-lxc-stack" }, "security_profile": { "requires_privileged_lxc": false, "source_requests_privileged_lxc": false, "optional_privileged_lxc": false, "requires_host_pid_namespace": false, "source_requests_relaxed_confinement": false, "requires_relaxed_confinement": false, "optional_relaxed_confinement": false, "risk_level": "normal", "confirmation_required": false, "warning": "The official Umami and PostgreSQL Compose services do not request privileged mode or relaxed host confinement." } }, "compatibility": { "automatic_install_candidate": true, "validated": false, "supported_compose_keys": [ "depends_on", "environment", "healthcheck", "image", "init", "ports", "restart", "volumes" ], "untranslated_blockers": [], "policy": "The official two-service Compose model is represented as two native OCI LXCs with a private PostgreSQL dependency and managed database storage. ProxMenux applies a first-start web-root check; validate the official heartbeat endpoint and login separately." }, "validation": { "schema": "passed", "clean_install": "passed", "service_health": "passed", "restart_persistence": "passed", "backup_restore": "pending", "update_preserves_data": "pending", "remove": "passed", "advanced_configuration": "pending", "storage_modes": "pending", "modify": "pending" }, "lifecycle": { "update_strategy": "resolve-latest-image-then-apply-reviewed-native-lxc-update", "registry_state": { "resolved_architecture": null, "resolved_digest": null, "image_version_label": null, "image_created": null }, "change_detection": "compare-compose-sha256-and-resolved-latest-image-digest", "automatic_unattended_updates": false, "dependency_lifecycle": { "implementation": "proxmox-hookscript", "trigger": "main-lxc-pre-start", "waits_for_dependency_healthchecks": true, "stops_dependencies_with_main": false } } }