Added compose-template.yaml and install script (wizard)

.env.runtime.example

@@ -0,0 +1,20 @@
+# Local runtime configuration for the deployment
+# Copy this file to .env.runtime and set the environment you want to deploy.
+# Supported values: sbx, dev, dev2, prod
+DOME_ENVIRONMENT=sbx
+
+# Uncomment to also start Dozzle (web UI for container logs, see README).
+# This is a standard Docker Compose profile: it applies to every start,
+# both manual (wizard.py) and automatic (update.sh via the systemd timer).
+#COMPOSE_PROFILES=debug
+
+# Git branch to pull versions-<environment>.env from (used by update.sh /
+# wizard.py step 3). Leave commented to use whichever branch is currently
+# checked out on this machine; update.sh warns if that isn't "main".
+#VERSIONS_BRANCH=main
+
+# Uncomment to keep a timestamped one-line record in LOG_FILE of every
+# wizard.py step/command run and every update.sh run that actually applied
+# a new version (not the full command output, and not the no-op ticks).
+#LOGGING=true
+#LOG_FILE=./access-node-compose.log

.github/workflows/ci-compose-up-test.yml

@@ -12,6 +12,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
+      - name: Generate runtime compose file
+        run: ./wizard.py generate
       - name: Start services
         run: docker compose -f compose.yaml up -d
       - name: Wait for containers to be healthy

.github/workflows/ci-compose-validation.yml

@@ -14,11 +14,10 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Create .env files from examples
-        run: |
-          for f in $(find . -name "*.example" -not -path "./.git/*"); do
-            cp "$f" "${f%.example}"
-          done
-
+        run: ./wizard.py init
+
+      - name: Generate runtime compose file
+        run: ./wizard.py generate
       - name: Validate Docker Compose file
         run: docker compose -f compose.yaml config
       - name: Check required metadata labels

.gitignore

@@ -12,13 +12,19 @@ Thumbs.db
 *.log
 *.tmp
 
+# Python bytecode cache (generated by running wizard.py)
+__pycache__/
+
 # Asset and build output folders
 assets/*
 !assets/.gitkeep
 
 # Misc
 *.bak
 
+# Config backups created by wizard.py before overwriting (contain secrets)
+*.tgz
+
 # Ignore everything in postgres-init except SQL files
 postgres-init/*
 !postgres-init/*.sql
@@ -27,5 +33,8 @@ postgres-init/*
 #Ignore customized .env files
 .env.desmos
 .env.dlt-adapter-alastria
+.env.runtime
 .secrets.desmos
-Caddyfile.example
+compose.yaml
+Caddyfile
+.compose-update.state

README.md

@@ -64,6 +64,57 @@ All architectural metadata must be prefixed with `dome.`, acting as our namespac
 4. **CI Validation:** Our (WIP) CI pipeline runs a checker. If a service is missing the `dome.owner` or `dome.type` labels, the build will fail.
 
 
+## Prerequisites
+
+Before running the installation wizard, make sure the target machine has:
+
+- **Docker Engine** and the **Docker Compose plugin** (`docker compose`, not the standalone `docker-compose`) — [install instructions](https://docs.docker.com/engine/install/).
+- **Python 3.8+** — used to run `wizard.py` (standard library only, no extra packages to install).
+- **git** — needed by `update.sh` to pull the latest `versions-<environment>.env` for periodic auto-updates; not required for a one-off manual install.
+- **systemd** (optional) — only needed if you want the wizard to install the auto-update timer for you (step 4); without it you can still set up your own scheduling, or update manually.
+
+`wizard.py` checks Docker and the Compose plugin automatically at startup (and on demand via step `1` of the menu) and stops with instructions if either is missing.
+
+## Installation
+
+The recommended way to install and configure the Access Node is the guided wizard:
+
+<pre> ./wizard.py</pre>
+
+It walks you through the following numbered steps, re-entrant at every run (safe to stop and relaunch at any point). Each step has both a number and a symbolic name — use whichever you prefer for direct/manual execution (e.g. `./wizard.py 5` and `./wizard.py start` are equivalent):
+
+| Step | Name | Description |
+| --- | --- | --- |
+| `1` | `preflight` | Checks Docker and the Compose plugin are installed; runs automatically at every startup, but can also be re-run on demand (e.g. after fixing something). |
+| `2` | `init` | Creates your working config files from the `.example` templates and tells you which ones to customize. |
+| `3` | `generate-compose` | Pulls the latest known-good image versions for your `DOME_ENVIRONMENT` (set in `.env.runtime`: `sbx`, `dev`, `dev2`, or `prod`) and generates `compose.yaml` from `compose-template.yaml`. |
+| `4` | `config-auto-update` | Offers to install and enable a systemd timer that periodically checks for new versions and restarts the stack (optional); if it can't install it automatically (no systemd, no sudo), it prints the manual steps. |
+| `5` | `start` | Runs `docker compose pull` and `docker compose up -d`. |
+
+The menu also lists a couple of lettered, non-sequential commands you can run at any point (they don't gate anything and are never auto-suggested as "the next step"):
+
+| Command | Name | Description |
+| --- | --- | --- |
+| `a` | `status` | A friendlier, condensed alternative to `docker compose ps`: one line per service with its up/down state and health. |
+| `b` | `backup` | Creates a timestamped `.tgz` backup of your current configuration files, on demand. |
+
+Run `./wizard.py` again at any time to resume where you left off, or jump directly to a step/command with `./wizard.py <number-letter-or-name>` (e.g. `./wizard.py 3` or `./wizard.py generate-compose`). Run `./wizard.py -h` for the full list.
+
+Step `3` (and `update.sh`'s automatic restarts) pull `versions-<environment>.env` from git. By default they use whichever branch is currently checked out on the machine; set `VERSIONS_BRANCH` in `.env.runtime` to pin a specific one (normally `main`). A yellow warning is printed whenever the branch in use isn't `main`, since that's not the intended production source.
+
+`wizard.py` is the only script meant to be run by hand. The only other one you'll see in the repo, `update.sh`, isn't for manual use either — it's what the systemd timer set up in step `4` calls periodically to check for new versions and restart the stack.
+
+### Logging
+
+Set `LOGGING=true` and (optionally) `LOG_FILE` in `.env.runtime` (default: `./access-node-compose.log`) to keep a timestamped record of every step or command actually run — one line each, not the full command output:
+
+```
+[2026.07.07 12.42.30] step 3) Pull updated versions and generate compose.yaml
+[2026.07.07 12.42.30] update.sh) regenerated compose.yaml for 'sbx' (dry run)
+```
+
+This applies both to manual wizard use and to `update.sh`'s automatic restarts via the systemd timer, so you get a single history of what ran and when. `update.sh` only adds a line when it actually finds and applies a new version — the periodic ticks where nothing changed stay silent, so the log doesn't fill up with no-ops.
+
 ## Configuration
 
 To correctly configure the stack, you need to edit the following configuration files.
@@ -90,22 +141,37 @@ Please make a copy of the provided .example files before to customize them
 
 Once you have the working files, you can customize them.
 
-You can also execure the script "setup.sh" to copy the working files from examples.
+Run `./wizard.py` to copy the working files from the examples for you (its first step) — see Installation above.
+
+`compose.yaml` itself is generated, not edited by hand: it never contains hardcoded image versions, only variables filled in from `versions-<environment>.env` (`./wizard.py generate`, called by `wizard.py` step 3 and by `update.sh` for the periodic auto-update).
 
 
 ## Execution
-You can execute the Access Node using the following command
 
-<pre> docker compose up -d</pre>
+The preferred way to start, restart, and check the Access Node is through the wizard (see Installation above):
+
+<pre> ./wizard.py 5</pre>
 
-To stop the stack, use this command
+This runs `docker compose pull` and `docker compose up -d` for you, automatically honoring any `COMPOSE_PROFILES` set in `.env.runtime` (see Dozzle below). To check the status of the running services afterwards:
+
+<pre> ./wizard.py a</pre>
+
+To stop the stack, use this command:
 
 <pre> docker compose down</pre>
 
+### Manual execution
+
+If you prefer not to use the wizard, once `compose.yaml` has been generated (see Installation above) you can start the stack directly with:
+
+<pre> docker compose up -d</pre>
+
+Keep in mind that running `docker compose` directly does not pick up `COMPOSE_PROFILES` from `.env.runtime` — export it yourself first if needed (e.g. `export $(grep -v '^#' .env.runtime | xargs)`), or pass `--profile <name>` explicitly. This also means manual runs stay out of sync with what `update.sh`'s automatic restarts will do, since those always read `.env.runtime`.
+
 ### Dozzle
 During setup/debug it is possible to start an instance of **Dozzle**, a service that provide a simple web UI to view container logs for all services, without having to view them from console.
 
-Dozzle will NOT be started automatically with docker compose unless you run the stack using this command 
+Dozzle will NOT be started automatically unless enabled. The recommended way is to uncomment `COMPOSE_PROFILES=debug` in your `.env.runtime` (see `.env.runtime.example`): this applies consistently both to `./wizard.py` (steps 5/a) and to `update.sh`'s automatic restarts via the systemd timer, so Dozzle doesn't silently disappear on the next auto-update. For a one-off manual start without touching `.env.runtime`, you can still run
 
 <pre> docker compose up -d --profile debug</pre>
 

compose.yaml → compose-template.yaml

@@ -7,7 +7,7 @@ services:
     # Service: TMF666 - Account Management
     # Purpose: Manages user accounts and profiles.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-account:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF666_account
     restart: always
     labels:
@@ -30,7 +30,7 @@ services:
     # Service: TMF651 - Agreement Management
     # Purpose: Manages commercial and technical agreements.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-agreement:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF651_agreement
     restart: always
     labels:
@@ -53,7 +53,7 @@ services:
     # Service: TMF678 - Customer Bill Management
     # Purpose: Handles invoicing and billing information.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-customer-bill-management:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF678_customer-bill-management
     restart: always
     labels:
@@ -76,7 +76,7 @@ services:
     # Service: TMF629 - Customer Management
     # Purpose: Manages customer information and lifecycle.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-customer-management:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     # Service: TMF629 - Customer Management
     # Service: TMF629 - Customer Management
     container_name: TMF629_customer-management
@@ -101,7 +101,7 @@ services:
     # Service: TMF632 - Party Management
     # Purpose: Repository for parties (organizations/individuals).
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-party-catalog:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF632_party-catalog
     restart: always
     labels:
@@ -124,7 +124,7 @@ services:
     # Service: TMF669 - Party Role Management
     # Purpose: Manages the roles played by parties.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-party-role:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF669_party-role
     restart: always
     labels:
@@ -147,7 +147,7 @@ services:
     # Service: TMF620 - Product Catalog Management
     # Purpose: Repository for products and services.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-product-catalog:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF620_product-catalog
     restart: always
     labels:
@@ -170,7 +170,7 @@ services:
     # Service: TMF637 - Product Inventory Management
     # Purpose: Manages the inventory of products.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-product-inventory:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF637_product-inventory
     restart: always
     labels:
@@ -193,7 +193,7 @@ services:
     # Service: TMF622 - Product Ordering Management
     # Purpose: Manages product orders.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-product-ordering-management:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF622_product-ordering-management
     restart: always
     labels:
@@ -216,7 +216,7 @@ services:
     # Service: TMF648 - Quote Management
     # Purpose: Manages product quotes.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-quote:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF648_quote
     restart: always
     labels:
@@ -239,7 +239,7 @@ services:
     # Service: TMF634 - Resource Catalog Management
     # Purpose: Repository for resources.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-resource-catalog:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF634_resource-catalog
     restart: always
     labels:
@@ -262,7 +262,7 @@ services:
     # Service: TMF664 - Resource Function Activation Management
     # Purpose: Manages resource function lifecycle.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-resource-function-activation:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF664_resource-function-activation
     restart: always
     labels:
@@ -285,7 +285,7 @@ services:
     # Service: TMF639 - Resource Inventory Management
     # Purpose: Manages resource inventory.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-resource-inventory:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF639_resource-inventory
     restart: always
     labels:
@@ -308,7 +308,7 @@ services:
     # Service: TMF633 - Service Catalog Management
     # Purpose: Repository for service definitions.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-service-catalog:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF633_service-catalog
     restart: always
     labels:
@@ -331,7 +331,7 @@ services:
     # Service: TMF638 - Service Inventory Management
     # Purpose: Manages service inventory.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-service-inventory:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF638_service-inventory
     restart: always
     labels:
@@ -354,7 +354,7 @@ services:
     # Service: TMF635 - Usage Management
     # Purpose: Manages service usage records.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-usage-management:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF635_usage-management
     restart: always
     labels:
@@ -377,7 +377,7 @@ services:
     # Service: TMF667 - Usage Management
     # Purpose: Manages service usage records.
     # Internal Ports: 8080 (API), 9090 (Admin/Metrics)
-    image: docker.io/drllbl18/tmforum-document-management:sbx_1.5.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: TMF667_document-management
     restart: always
     labels:
@@ -404,7 +404,8 @@ services:
   minio:
     # Service: MINIO S3 STORAGE
     # Purpose: This service provides S3-compatible object storage for the Access Node.
-    image: minio/minio:latest
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
+    container_name: minio
     command: server /data --console-address :9001
     ports:
       - "9000:9000"   # S3 API
@@ -441,7 +442,7 @@ services:
     # Service: DESMOS
     # Purpose: Manages replication of data across nodes in the DOME ecosystem.
     # Internal Ports: 8080 (API)
-    image: in2workspace/in2-desmos-api:v2.0.11
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: desmos
     restart: always
     depends_on:
@@ -504,7 +505,7 @@ services:
     # Service: DLT Adapter Alastria
     # Purpose: Interface for Alastria DLT.
     # Internal Ports: 8080 (API)
-    image: quay.io/digitelts/dlt-adapter:1.5.1
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: dlt-adapter-alastria
     restart: always
     labels:
@@ -527,7 +528,7 @@ services:
     # Service: Scorpio Broker
     # Purpose: Context Broker for NGSI-LD data.
     # Internal Ports: 9090
-    image: scorpiobroker/all-in-one-runner:java-4.1.10
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: scorpio
     restart: always
     depends_on:
@@ -549,7 +550,7 @@ services:
 
   postgres:
     # Service: PostgreSQL Database
-    image: postgis/postgis:15-3.4
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: postgres
     restart: always
     labels:
@@ -575,7 +576,7 @@ services:
     # Service: Caddy API Gateway
     # Purpose: Single entry point for all external traffic entering Access Node.
     # Ports: 80 (HTTP exposed), 443 (HTTPS)
-    image: caddy:2-alpine
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     container_name: caddy
     restart: always
     ports:
@@ -604,7 +605,7 @@ services:
     # Note: Dozzle is disabled by default and can be enabled via Docker Compose profiles, or by running the stack with `docker compose --profile debug up -d`.
     #       If you want to enable Dozzle by default, remove or comment the `profiles` directive below, or run the stack with `docker compose --profile debug up -d`.
     container_name: dozzle
-    image: amir20/dozzle:latest
+    image: __CONTAINER_IMAGE_PLACEHOLDER__
     environment:
       - DOZZLE_BASE=/dozzle
     ports: