Docker — E2E status

Later operator-declared e2202ac qualification is recorded on Live E2E Acceptance. This page keeps the earlier written lab narrative.

Status summary

Evidence	Value
IMPLEMENTED	YES (Linux offline-image + Windows Docker scripts and deploy/docker/*)
STATIC / AUTOMATED	Linux Docker offline package / deploy / auto-update script tests
LIVE E2E VALIDATED	Linux Docker install BLOCKED / RETEST REQUIRED; Windows Docker RETEST REQUIRED

Linux Docker — offline prebuilt image (current production model)

Evidence	Value
IMPLEMENTED	YES
AUTOMATED TESTED	YES (docker_deploy_test.sh, package_docker_linux_test.sh, auto_update_test.sh)
Offline package / image / docker load / security	LIVE PASS
Offline clean install	LIVE PASS
Reboot recovery	LIVE PASS
NO-OP update	LIVE PASS
ForceRedeploy	LIVE FAIL / RETEST REQUIRED
Rollback	BLOCKED (pending ForceRedeploy fix)
Linux Docker install (current package after HostPort fix)	LIVE PASS

ForceRedeploy live failure

sudo bash ./scripts/update.sh --force-redeploy ran check, migrate, compose up, live/ready, and metadata, but the running container was not recreated (Container iqv-integration-api-api-1 Running; container ID and StartedAt unchanged).

Root cause: docker compose up -d is a no-op when the image and Compose config are unchanged. Explicit --force-redeploy must pass --force-recreate.

Do not mark ForceRedeploy Live PASS until retest after this fix.

Live install blocker (HostPort false-positive)

On the Ubuntu host, 4242 was free:

• systemctl is-active iqv-integration-api → inactive
• ss -lntp | grep ':4242 ' → no socket rows
• no Docker container

The installer still reported HostPort 4242 is occupied / HostPort 4242 conflict.

Root cause: ss -ltnp "sport = :${host_port}" can print a column header when there is no listener. The preflight treated any non-empty text as occupancy. This was not a real port conflict.

Fix: occupancy requires a real TCP listen row (header-free ss -H / filtered LISTEN lines). IPv4/IPv6/0.0.0.0/::/loopback/specific binds are detected. Stopped-container metadata is not treated as a live listener.

Do not mark Linux Docker install as Live PASS until retest after this fix.

Recommended production path after this model:

• Offline OCI docker save archive in the release package
• External MongoDB only (operator host/database; no private lab IPs in public docs)
• Host ports as configured (example 4242:4242) on the Ubuntu lab API host
• No Go / Git / source / registry / internet on the customer host
• No MongoDB container and no MongoDB install on the API host

Next Ubuntu live test plan (operator-run; not executed here)

1. Confirm Docker Engine + Compose on the Ubuntu lab API host (do not install Docker from the package).
2. Transfer iqv-integration-api-<version>-linux-docker-amd64 (no source tree required).
3. install.sh --external-mongodb --mongo-uri mongodb://<MONGODB_HOST>:27017 --mongo-database <DATABASE_NAME> --integration-actor-user-id <EXISTING_ACTIVE_USER_OBJECT_ID> --host-port 4242 --container-port 4242 --public-base-url http://<API_HOST>:4242
4. status.sh — External MongoDB, actor=configured, live/ready, security flags, auto-update disabled.
5. Reboot — unless-stopped brings the API back.
6. Same-package update.sh → NO-OP.
7. New package image → transactional update; --test-fail-at AfterComposeUp → snapshot rollback; metadata preserved; Mongo untouched.
8. Optional: enable auto-update only against a trusted LAN manifest; default remains disabled.

Do not mark Linux Docker Live E2E PASS until that retest completes.

---

In this development / Windows lab environment, live E2E with a Docker daemon (docker build / compose up / container health / host reboot) was not performed → NOT RUN / NOT E2E VALIDATED.

Pre-E2E tooling readiness (automated): explicit -EnvFile / --env-file, separate HostPort/ContainerPort (IQV_HOST_PORT vs HTTP_PORT), compose ${IQV_HOST_PORT}:${HTTP_PORT}, HostPort-only conflict preflight. Windows PowerShell DockerDeploy tests: automated PASS. Live install still NOT E2E VALIDATED.

Windows Docker Live E2E — Attempt #1

Evidence	Value
Status	LIVE E2E IN PROGRESS / RETEST REQUIRED
Overall PASS	NO

Observed PASS (real host)

Step	Result
Repository / explicit EnvFile	PASS
Docker availability	PASS
HostPort 4243 free (native API remains on 4242)	PASS
External MongoDB URI validation	PASS
SkipGitPull / compose selection / image tag	PASS
Docker Compose config (mapping 4243→4242)	PASS
Container → host.docker.internal:27017 TCP	PASS

Detected and Fixed / Retest Required

Issue	Root cause	Fix	Retest
Docker test-stage aborted	PowerShell 5.1 2>&1 + $ErrorActionPreference=Stop treated BuildKit stderr progress as NativeCommandError	Central Invoke-IQVNativeCommand (exit-code based)	RETEST REQUIRED
Resolved compose config printed secrets (AUTH_CLIENT_SECRET, AUTH_JWT_SECRET)	docker compose config return value leaked to pipeline; success path printed full render	config --quiet + never return/print resolved config; failure output redacted	RETEST REQUIRED

Do not mark Windows Docker Live E2E as PASS until retest completes.

Operations reference: Docker installation, Update and rollback.

Windows Docker Live E2E — Attempt #2

Evidence	Value
Status	LIVE E2E IN PROGRESS / RETEST REQUIRED
Overall PASS	NO

Observed PASS before failure

Step	Result
EnvFile resolution	PASS
HostPort / ContainerPort separation (4243 / 4242)	PASS
HostPort preflight (native 4242 not treated as conflict)	PASS
External MongoDB validation	PASS
SkipGitPull + AllowDirty	PASS
Dirty image provenance (2c1590c-dirty)	PASS

Failure

Issue	Detail
Symptom	docker compose config failed with exit 125: unknown flag: --env-file / Usage: docker [OPTIONS] COMMAND
Root cause	Compose option --env-file was placed before the compose token → Docker root CLI
Incorrect layout	docker --env-file <file> ... config
Correct layout	docker compose --env-file <file> -f <compose> --project-directory <root> config --quiet

Detected / Fixed / Automated / Retest

Item	Status
Detected	YES (Attempt #2)
Fixed	New-IQVDockerComposeArgumentList / Invoke-IQVDockerCompose force compose first
Automated regression	YES (ordering + spaced-path tests)
Live Retest Required	YES

Windows Docker overall status remains LIVE E2E IN PROGRESS / RETEST REQUIRED.

Operations reference: Docker installation, Update and rollback.

Lab retest hint

Dirty working tree (uncommitted Docker tooling) requires explicit -AllowDirty (image tag becomes <sha>-dirty, source_dirty=true). -SkipGitPull does not allow dirty trees. Align PUBLIC_BASE_URL with HostPort when using a direct http://ip:port URL (installer never rewrites it).

Windows Docker Live E2E — Attempt #3 prep (controlled rollback)

Evidence	Value
Status	RETEST REQUIRED
Overall PASS	NO
Live E2E	NOT RUN (lab tooling only)

Lab-only tooling added (automated)

Item	Detail
-TestFailAt AfterComposeUp	Injects failure after compose up so automatic rollback can be exercised
Immutable rollback snapshot	Before runtime image mutation, running API image ID is tagged iqv-integration-api:rollback-<short-id>-<timestamp>
Same-tag ForceRedeploy safety	Rollback uses snapshot, not an overwritten target tag (e.g. deployed=2c1590c-dirty == ForceRedeploy target)
MongoDB	Container/volume not rolled back; Database rollback = NOT PERFORMED
Exit code	Successful rollback still returns original non-zero update exit code
Metadata	Failed update does not overwrite deployment metadata
Snapshot cleanup	After successful deploy or after successful rollback retag

Controlled Windows Docker rollback path = RETEST REQUIRED (do not mark Live E2E PASS until lab retest with -TestFailAt AfterComposeUp completes).

Suggested lab command (user-run; not executed here)

powershell .\scripts\windows\docker\update.ps1 -SkipGitPull -AllowDirty -ForceRedeploy ` -EnvFile .\.env.docker.external -HostPort 4243 -ContainerPort 4242 ` -SkipTests -TestFailAt AfterComposeUp

Expect: non-zero exit, previous API restored via snapshot, Mongo untouched, /health/live + /health/ready healthy.

Port conflict exit code

Common port-conflict code for Windows/Linux Docker and native installers: 15 (EXIT_PORT_CONFLICT / EXIT_PORT).
If the Docker daemon is absent, Windows Docker scripts may exit 16 (EXIT_DOCKER_NA).

Next phase — Plan A: External MongoDB

API container → host.docker.internal / external address → host or external MongoDB.

#	Step	Status
1	Prerequisites (Docker Engine / Compose)	NOT E2E VALIDATED
2	External MongoDB reachable	NOT E2E VALIDATED
3	.env (external URI; no secrets in logs)	NOT E2E VALIDATED
4	install (compose up)	NOT E2E VALIDATED
5	container health / health/live / health/ready	NOT E2E VALIDATED
6	container restart	NOT E2E VALIDATED
7	host reboot	NOT E2E VALIDATED
8	update	NOT E2E VALIDATED
9	NO-OP update	NOT E2E VALIDATED
10	rollback	NOT E2E VALIDATED
11	config preservation	NOT E2E VALIDATED
12	volume preservation (named volumes if any)	NOT E2E VALIDATED
13	uninstall (opt-in volume delete policy)	NOT E2E VALIDATED

No PASS yet.

Next phase — Plan B: Bundled MongoDB

API container → Docker internal network → MongoDB container → persistent volume.

#	Step	Status
1	Prerequisites	NOT E2E VALIDATED
2	Bundled compose profile / stack	NOT E2E VALIDATED
3	.env	NOT E2E VALIDATED
4	install	NOT E2E VALIDATED
5	API + Mongo container health	NOT E2E VALIDATED
6	container restart	NOT E2E VALIDATED
7	host reboot	NOT E2E VALIDATED
8	update	NOT E2E VALIDATED
9	NO-OP update	NOT E2E VALIDATED
10	rollback	NOT E2E VALIDATED
11	config preservation	NOT E2E VALIDATED
12	Mongo volume persistence	NOT E2E VALIDATED
13	uninstall (volume preserve / delete flags)	NOT E2E VALIDATED

No PASS yet.

Platform note

Platform	Live E2E
Linux Docker	NOT E2E VALIDATED
Windows Docker	NOT E2E VALIDATED

Related

• Test matrix
• Linux systemd E2E
• Known untested scenarios
• Installer validation matrix