From 0c6139236c5bc985f32d8fde63aea887d0006286 Mon Sep 17 00:00:00 2001
From: Matti Airas <matti.airas@hatlabs.fi>
Date: Thu, 19 Feb 2026 23:10:02 +0200
Subject: [PATCH] docs: clarify container app two-phase install process

Explain that .deb packages are small metadata-only packages and
that the actual Docker image pull happens on first service start,
which is the slow part of installation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/architecture/package-system.md | 11 ++++++++---
 docs/user-guide/installing-apps.md  | 21 ++++++++++++++-------
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/docs/architecture/package-system.md b/docs/architecture/package-system.md
index 4d93f94..23af6f2 100644
--- a/docs/architecture/package-system.md
+++ b/docs/architecture/package-system.md
@@ -30,6 +30,8 @@ Each container app package contains:
 └── {app-name}.png              # Icon for store and dashboard
 ```
 
+The package is intentionally lightweight — it does **not** contain the Docker image itself. The actual container image is pulled from the registry when the service starts for the first time. This keeps packages small (a few kilobytes) and ensures you always get the exact image version specified in the compose file.
+
 The systemd service runs `docker compose up -d` on start and `docker compose down` on stop.
 
 ## App Definition Format
@@ -151,10 +153,13 @@ The CI/CD pipeline builds packages on push to main, publishes to unstable, and p
 
 ```
 apt install marine-grafana-container
-  → dpkg extracts files
+  → dpkg extracts files (seconds — package is small)
   → postinst creates data directories, generates secrets
   → systemd starts grafana-container.service
-    → docker compose up -d
+    → prestart.sh computes runtime configuration
+    → docker compose up
+      → Docker pulls image layers from registry (may take minutes on first install)
+      → Container starts
       → Traefik detects labels, creates route
       → mDNS publisher advertises grafana.halos.local
       → Homarr adapter adds dashboard tile
@@ -178,7 +183,7 @@ apt remove marine-grafana-container
 apt upgrade
   → dpkg extracts updated files
   → systemd restarts the service
-    → docker compose pulls new image and recreates container
+    → docker compose pulls new image (only if upstream version changed) and recreates container
   → Persistent data in /var/lib/container-apps/{app}/ is preserved
 ```
 
diff --git a/docs/user-guide/installing-apps.md b/docs/user-guide/installing-apps.md
index e8c8679..3a9109c 100644
--- a/docs/user-guide/installing-apps.md
+++ b/docs/user-guide/installing-apps.md
@@ -6,13 +6,20 @@ HaLOS provides a container app store — a curated collection of applications pa
 
 ## How it works
 
-Each container app is a standard Debian package (`.deb`) that contains:
+Installing a container app is a two-phase process:
 
-- A Docker Compose file defining the container(s)
-- A systemd service that manages the container lifecycle
-- Docker labels for Traefik routing and Homarr dashboard integration
+1. **Package install (fast)** — HaLOS downloads and installs a small package that describes how to run the app. This takes only a few seconds.
 
-When you install an app, `apt` downloads the package, `systemd` starts the container, Traefik picks up the routing labels, and the app appears on your [dashboard](dashboard.md) — all automatically.
+2. **Image pull (slow)** — The app's actual software is then downloaded from the internet. This can take anywhere from 30 seconds to several minutes depending on the app size and your network speed.
+
+The app only becomes accessible after the download completes and the app starts. It then appears on your [dashboard](dashboard.md) automatically.
+
+??? info "Under the hood"
+    The package is a standard Debian `.deb` containing a Docker Compose file
+    (which defines the containers to run), a systemd service (which manages
+    the app lifecycle), and metadata for routing and dashboard integration.
+    The heavy download in phase 2 is Docker pulling the container image
+    layers from a registry.
 
 ## Browsing the store
 
@@ -26,8 +33,8 @@ The store shows apps from all configured stores. The Marine variant adds a dedic
 
 1. Click on an app to view its details (description, version, dependencies).
 2. Click **Install**.
-3. Wait for the package to download and the container to start (typically 30–60 seconds).
-4. The app appears on your Homarr dashboard and is accessible via its subdomain URL.
+3. The package installs quickly, but the app needs time to pull its Docker image on first start. Small apps are ready within a minute; larger ones (e.g., Grafana, OpenCPN) may take several minutes on slower connections.
+4. Once the image pull completes, the app appears on your Homarr dashboard and is accessible via its subdomain URL.
 
 ## Managing installed apps