Docker Installation¶

Deployment Type

Docker is a separate deployment type from native OS services. For native Windows Service deployment, see Windows Service Installation. For native Linux systemd deployment, see Linux systemd Installation.

Validation evidence

IMPLEMENTED = YES. Older written lab pages: Windows Docker RETEST REQUIRED; Linux Docker ForceRedeploy historically LIVE FAIL then code-fixed. Operator-declared commit e2202ac qualification is on Live E2E. See also Docker E2E.

Linux Docker — RECOMMENDED PRODUCTION

Prebuilt offline OCI image archive + external / existing MongoDB.

No Go, no Git, no source, no registry pull, no docker build, no internet on the customer host.

Docker Engine + Compose are prerequisites (not included in the package).

Bundled MongoDB is development/lab/optional legacy only — not the production recommendation.

Full Ubuntu guide: Ubuntu Docker Installation.

Linux Production Recommendation

On Linux, both systemd (offline prebuilt binary) and Docker (offline prebuilt image) are recommended production methods. Choose based on operational standards. Both use external MongoDB.

Prerequisites¶

Windows¶

Windows Server 2016+ or Windows 10/11 (64-bit)
Docker Desktop or Docker Engine for Windows
PowerShell 5.1+
Administrator privileges

Linux (production offline package)¶

Ubuntu 24.04 amd64
Docker Engine + Docker Compose v2 already installed
sudo / root privileges
Offline package iqv-integration-api-<version>-linux-docker-amd64 (image tar + scripts)
External MongoDB reachable from the container network (real host/IP; not loopback)

The Linux production installer never installs Docker Engine.

Common¶

MongoDB 6.0+ as a separate existing service
Windows Docker may use host.docker.internal for host MongoDB
Linux Docker production uses the operator-supplied URI as-is (no host.docker.internal rewrite)

MongoDB Is a Separate Service

The Docker installer does not install or manage MongoDB. MongoDB must be accessible before you start the container.

Installation¶

Windows¶

Open an elevated PowerShell prompt and run:

powershell powershell.exe -ExecutionPolicy Bypass -File .\scripts\windows\docker\install.ps1

Linux (offline production package)¶

From the extracted offline package (not from a Git checkout):

bash sudo ./scripts/install.sh \ --external-mongodb \ --mongo-uri "mongodb://<MONGODB_HOST>:27017" \ --mongo-database champion \ --integration-actor-user-id "REAL_USER_OBJECT_ID" \ --host-port 4242 \ --container-port 4242 \ --public-base-url "http://<API_HOST>:4242"

See Ubuntu Docker Installation.

What the Linux offline installer does¶

Validates root, Docker Engine, Compose, and amd64.
Verifies manifest.json and image tar SHA256 (mismatch → no docker load, no mutation).
Bootstraps env from config/.env.example + CLI (existing env is preserved).
Validates integration actor format (never generates a random ObjectID).
docker load (no pull, no build).
Validates compose (API-only; no build:).
Host port preflight, read-only check, one-shot migrate, compose up -d --no-build.
/health/live and /health/ready, then metadata.

Windows installer behavior is unchanged (see above).

Environment Configuration¶

The installer never auto-creates an env file. Provide repository .env or an explicit file:

```bash cp .env.example .env

or a Docker-only file (gitignored), e.g. .env.docker.external¶

```

Windows — EnvFile / HostPort / ContainerPort¶

powershell .\scripts\windows\docker\install.ps1 ` -ExternalMongoDB ` -EnvFile .\.env.docker.external ` -HostPort 4243 ` -ContainerPort 4242 ` -SkipGitPull

Concept	Meaning
`HostPort` (`IQV_HOST_PORT`)	Published on the host (`0.0.0.0:4243`)
`ContainerPort` (`HTTP_PORT`)	Listen port inside the container (`4242`)
Compose mapping	`${IQV_HOST_PORT}:${HTTP_PORT}` → `4243:4242`
Compose `--env-file`	Interpolation only (ports, image tag, `IQV_ENV_FILE` path)
Service `env_file`	Container runtime env (secrets). Not the same as interpolation

Native Windows Service on 4242 can keep running while Docker publishes 4243. Only HostPort is preflight-checked for conflicts (exit 15).

Linux production (offline package)¶

--skip-git-pull is rejected. Linux Docker production does not use Git.

bash sudo ./scripts/install.sh \ --external-mongodb \ --mongo-uri "mongodb://<MONGODB_HOST>:27017" \ --mongo-database champion \ --integration-actor-user-id "REAL_USER_OBJECT_ID" \ --host-port 4242 \ --container-port 4242 \ --public-base-url "http://<API_HOST>:4242"

--env-file remains optional. Without it, the package config/.env.example is staged. Existing /etc/iqvizyon/iqv-integration-api.docker.env is never overwritten.

Linux Docker: offline install / reboot / NO-OP LIVE PASS. ForceRedeploy LIVE FAIL / RETEST REQUIRED (compose up -d did not recreate an unchanged container; fix: --force-recreate). Rollback is blocked until that retest.

Edit the file and set all required values — at minimum MONGODB_URI, AUTH_CLIENT_SECRET, AUTH_JWT_SECRET.

Secrets

Never log or share the contents of env files. Secrets are never written to application logs or deployment metadata.

Connecting to Host MongoDB¶

When MongoDB runs on the Docker host (not in a container):

Windows Docker Desktop: use host.docker.internal:

text MONGODB_URI=mongodb://host.docker.internal:27017/iqv_integration

Linux production: use the real MongoDB host or IP. The installer never rewrites the URI to host.docker.internal. Production compose has no extra_hosts dependency.

text MONGODB_URI=mongodb://<MONGODB_HOST>:27017 MONGODB_DATABASE=champion

Loopback (localhost / 127.0.0.1 / ::1) fails closed (that address is the container itself).

Loopback (localhost / 127.0.0.1 / ::1) in MONGODB_URI fails closed for external MongoDB mode. Installers never rewrite your URI.

When using --with-mongodb / -WithMongoDB, the API uses Compose DNS mongodb://mongodb:27017 (not the host MongoDB URI).

MongoDB Is a Separate Service

The Docker installer does not install or manage an external MongoDB. For bundled MongoDB, use -WithMongoDB / --with-mongodb explicitly.

Optional Compose MongoDB Profile¶

For development or testing with a local MongoDB container:

bash docker compose -f docker-compose.yml -f docker-compose.local.yml --profile local-db up --build -d

Warning

The local-db profile is for development only. Production deployments should use the customer's existing MongoDB service.

Container Management¶

Status¶

bash docker compose ps docker compose logs --tail=50

Stop¶

bash docker compose stop

Restart¶

bash docker compose restart

Remove¶

bash docker compose down

MongoDB Data

docker compose down does not delete MongoDB data (whether MongoDB runs on the host or in a separate container with a named volume). Your database remains intact.

Rebuild and Update¶

Windows / lab (source tree): docker compose up --build -d remains a development path.

Linux production: do not build on the customer host. Transfer a new offline package and run:

bash sudo ./scripts/update.sh

Same image digest → NO-OP. See Update and Rollback.

Firewall Configuration¶

Windows¶

powershell New-NetFirewallRule -DisplayName "IQV Integration API (Docker)" ` -Direction Inbound -Protocol TCP -LocalPort 8080 ` -Action Allow -Profile Domain,Private

Linux¶

bash sudo ufw allow 8080/tcp comment "IQV Integration API (Docker)"

Port Conflicts

If port 8080 is already in use on the host, the container will fail to start. Change the port mapping in your compose file or stop the conflicting process.

Logging¶

View container logs:

bash docker compose logs -f

Secrets, tokens, and credentials are never written to logs.

Exit Codes¶

Code	Meaning
0	Success
1	General error
2	Configuration error
3	MongoDB connection failure
4	MongoDB authentication failure
5	MongoDB timeout
6	Port already in use
7	TLS certificate error
8	Permission denied
9	Binary not found
10	Service registration failure
11	Health check failure
12	Backup failure
13	Restore failure
14	Migration failure
15	Dirty repository
16	Network error
17	Unknown error

Troubleshooting¶

DATABASE_UNAVAILABLE¶

The container cannot reach MongoDB. Verify:

MongoDB is running on the host or in a reachable container.
MONGODB_URI uses the correct hostname (host.docker.internal for host MongoDB, service name for compose MongoDB).
MongoDB authentication credentials are valid.
Docker network configuration allows the container to reach the MongoDB port.

Port Conflict (Exit Code 6)¶

The host port is already in use. Check:

```bash

Linux¶

sudo ss -tlnp | grep 8080

Windows¶

Get-NetTCPConnection -LocalPort 8080 | Select-Object OwningProcess ```

Migration Failure (Exit Code 14)¶

A database migration failed. Do not retry automatically. Inspect the container logs, fix the issue, then rebuild or rollback. See Update and Rollback.

Offline Installation (Linux production)¶

Recommended path: build and package on CI, then install from the self-contained archive.

```bash

Development / CI (has Go + Docker + source)¶

./scripts/release/build-docker-linux.sh ./scripts/release/package-docker-linux.sh ```

Transfer iqv-integration-api-<version>-linux-docker-amd64.tar.gz to the Ubuntu host. Extract and run scripts/install.sh as shown above. The installer verifies SHA256 and runs docker load. It does not call Git, Go, docker build, docker pull, curl/wget downloads, or apt.

Optional auto-update (default disabled) discovers a versioned release manifest over HTTPS or a trusted LAN path, verifies SHA256, and reuses update.sh. It is not git pull. Manual offline update always remains available.

Health Checks¶

Both liveness and readiness probes must pass before a deployment is considered successful:

Endpoint	Purpose
`GET /health/live`	Process is alive
`GET /health/ready`	Process is alive and MongoDB is reachable

The installer scripts automatically verify both endpoints. Do not report success if either probe fails.