Merge pull request #10 from worryboy/feature/containerize-schlundtech

changes

Author: worryboy

.env.dns.example

@@ -17,6 +17,8 @@ ENABLE_IPV4=true
 ENABLE_IPV6=false
 
 # Run once with DRY_RUN=true before switching to continuous live updates.
+# Use docker compose run --rm internetx-dyndns for RUN_ONCE=true validation.
+# Use RUN_ONCE=false with docker compose up -d for continuous mode.
 DRY_RUN=true
 FORCE_UPDATE_ON_NO_CHANGE=false
 RUN_ONCE=true

.env.example

@@ -56,6 +56,8 @@ DRY_RUN=true
 # even in that no-change case.
 # FORCE_UPDATE_ON_NO_CHANGE=false
 # RUN_ONCE=true: execute a single check cycle and exit instead of looping.
+# Use docker compose run --rm internetx-dyndns for one-shot validation.
+# Use RUN_ONCE=false with docker compose up -d for continuous mode.
 RUN_ONCE=true
 # DEBUG=true: print detailed diagnostic logging without exposing secrets,
 # including sanitized XML request/response payloads. Passwords and session

CHANGELOG.md

@@ -11,6 +11,8 @@
 - Added `.env.dns.example` and wired the example compose file to `.env.dns` to keep DNS settings separate from the Traefik/CrowdSec stack `.env`.
 - Documented how the example extends, but does not replace, the goNeuland Traefik/CrowdSec guide and migration note.
 - Updated example documentation for outbound-only DynDNS operation, Compose startup ordering, DNS propagation limits, and `PUSHOVER_LOCATION_PREFIX=Berlin`.
+- Clarified `RUN_ONCE=true` usage with Docker Compose and added a startup warning for restart-policy loops.
+- Improved Dockerfile package/install hygiene and kept the expensive PHP extension build layer cacheable.
 - Updated release references to `0.4.0`.
 
 ## 0.3.0 - Multi-Target And Notifications

README.Docker.md

@@ -187,6 +187,14 @@ docker run --rm \
   worryboy/internetx-dyndns:0.4.0
 ```
 
+For Compose validation with `RUN_ONCE=true`, use:
+
+```bash
+docker compose run --rm internetx-dyndns
+```
+
+Do not use `docker compose up -d` for `RUN_ONCE=true` validation with the default restart policy. The worker exits cleanly after one cycle, then Docker starts it again because `restart: unless-stopped` is intended for continuous mode.
+
 Run continuously:
 
 ```bash
@@ -205,6 +213,7 @@ docker run -d \
 Start with the Docker-Hub-oriented Compose file:
 
 ```bash
+# set RUN_ONCE=false in .env first
 docker compose -f docker-compose.hub.yml up -d
 ```
 
@@ -230,6 +239,7 @@ In dry-run mode, the worker may:
 - log what would happen
 
 It never sends a live DNS mutation while `DRY_RUN=true`.
+With `RUN_ONCE=true`, prefer `docker compose run --rm internetx-dyndns`.
 
 For normal long-running updates, switch to:
 

README.md

@@ -209,6 +209,8 @@ docker compose build
 docker compose run --rm internetx-dyndns
 ```
 
+Use `docker compose run --rm internetx-dyndns` when `RUN_ONCE=true`. Do not use `docker compose up -d` for one-shot validation with the default restart policy, because Docker will restart the cleanly exited container and it can look like a failure loop.
+
 The recommended validation flags are:
 
 ```env
@@ -219,7 +221,7 @@ DEBUG=true
 
 - `DRY_RUN=true` validates config, detects the public IP, creates and closes an InterNetX AuthSession, may run read-only InterNetX zone validation, compares state, and logs what would happen without sending a live DNS update.
 - `FORCE_UPDATE_ON_NO_CHANGE=false` is the default and avoids unnecessary live update requests when the detected public IP is unchanged and every target already matches that IP.
-- `RUN_ONCE=true` executes a single check cycle and exits instead of looping continuously.
+- `RUN_ONCE=true` executes a single check cycle and exits instead of looping continuously. It is meant for `docker compose run --rm internetx-dyndns`.
 - `DEBUG=true` prints detailed diagnostic logging without exposing passwords, session hashes, or sensitive credentials. Provider request/response payloads are sanitized and labeled as `auth_session_create`, `read_only_preflight`, `live_mutation`, or `session_cleanup`.
 - With `DEBUG=true`, the worker logs each runtime stage as it moves through config validation, public IP detection, authentication/session preflight, target validation, update decision, live mutation, and session cleanup.
 - If `PUSHOVER_APP_KEY`, `PUSHOVER_USER_KEY`, and `PUSHOVER_LOCATION_PREFIX` are all configured, the worker can send a Pushover notification when a real public IP change is detected.
@@ -341,12 +343,14 @@ Build and run continuously:
 
 ```bash
 cp .env.example .env
-# edit .env
+# edit .env and set RUN_ONCE=false
 docker compose build
 docker compose up -d
 docker compose logs -f
 ```
 
+Use `docker compose up -d` for continuous mode with `RUN_ONCE=false`. The compose file has `restart: unless-stopped`, so `RUN_ONCE=true` will exit successfully and then be started again by Docker.
+
 Run one safe validation cycle:
 
 ```bash

README.traefik-crowdsec-example.md

@@ -93,9 +93,12 @@ Validate the DNS worker first:
 docker compose -f docker-compose.traefik-crowdsec-example.yml run --rm internetx-dyndns
 ```
 
+This is the preferred command while `RUN_ONCE=true`. Do not use `up -d` for one-shot validation, because the example compose file uses `restart: unless-stopped` for the later continuous mode.
+
 Start the stack:
 
 ```bash
+# set RUN_ONCE=false in .env.dns first
 docker compose -f docker-compose.traefik-crowdsec-example.yml up -d
 ```
 

docker-compose.hub.yml

@@ -2,6 +2,8 @@ services:
   internetx-dyndns:
     image: worryboy/internetx-dyndns:latest
     container_name: internetx-dyndns
+    # For RUN_ONCE=true, use: docker compose run --rm internetx-dyndns.
+    # This restart policy is intended for continuous RUN_ONCE=false operation.
     restart: unless-stopped
     read_only: true
     cap_drop:

docker-compose.traefik-crowdsec-example.yml

@@ -2,6 +2,9 @@ services:
   internetx-dyndns:
     image: worryboy/internetx-dyndns:0.4.0
     container_name: internetx-dyndns
+    # For RUN_ONCE=true, validate with:
+    # docker compose -f docker-compose.traefik-crowdsec-example.yml run --rm internetx-dyndns
+    # This restart policy is intended for continuous RUN_ONCE=false operation.
     restart: unless-stopped
     read_only: true
     cap_drop:

docker-compose.yml

@@ -4,6 +4,8 @@ services:
       context: .
     container_name: internetx-dyndns
     image: internetx-dyndns:local
+    # For RUN_ONCE=true, use: docker compose run --rm internetx-dyndns.
+    # This restart policy is intended for continuous RUN_ONCE=false operation.
     restart: unless-stopped
     read_only: true
     cap_drop:

docker/start.sh

@@ -4,6 +4,7 @@ set -eu
 mkdir -p "${STATE_DIR:-/app/state}"
 
 if [ "${RUN_ONCE:-false}" = "true" ] || [ "${RUN_ONCE:-false}" = "1" ]; then
+  echo "RUN_ONCE=true: executing one cycle and exiting. With Docker Compose, prefer 'docker compose run --rm internetx-dyndns'; 'docker compose up -d' with a restart policy will start it again." >&2
   exec php /app/bin/dyndns.php
 fi