Skip to content

Ubuntu Docker Installation

Separate Deployment Type

Docker is a separate deployment type from the native systemd service. Native Linux production remains Ubuntu Native Installation.

RECOMMENDED DOCKER PRODUCTION

Prebuilt offline OCI image archive + external / existing MongoDB.

Customer host: no Go, no Git, no source, no registry, no internet, no docker build, no docker pull.

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

Bundled MongoDB compose is development / lab / optional legacy only. It is not the recommended production path.

Live E2E for this offline image model: RETEST REQUIRED. See Docker E2E.

Prerequisites (production host)

  • Ubuntu 24.04 amd64 (supported target)
  • Docker Engine (already installed and running)
  • Docker Compose v2 plugin (docker compose)
  • sudo / root
  • Reachable external MongoDB (not installed by this package)

If Docker is missing, installers fail closed and do not download or install Docker:

text Docker Engine is not installed. Install the supported Docker runtime before deploying IQV Integration API.

Development / CI → customer package

text source + Go + Docker build ↓ immutable OCI image (iqv-integration-api:<version>) ↓ docker image archive ↓ offline release package ↓ Ubuntu customer server (Docker Engine + Compose only) ↓ API container → external MongoDB

On a development or CI machine (internet allowed):

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

Production packages require a clean working tree. Development override: --allow-dirty.

Package layout:

text iqv-integration-api-<version>-linux-docker-amd64/ ├── image/iqv-integration-api-<version>.tar ├── deploy/compose.yml ├── scripts/install.sh update.sh status.sh uninstall.sh ├── config/.env.example ├── manifest.json ├── SHA256SUMS ├── README.en.md └── README.tr.md

Offline production install

MongoDB is not deployed. Use the customer MongoDB host and database name.

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"

  • The MongoDB URI is used as-is. It is never rewritten to host.docker.internal.
  • --integration-actor-user-id must be an existing active user ObjectID. A random ID is never generated.
  • Existing runtime env (/etc/iqvizyon/iqv-integration-api.docker.env) is preserved on reinstall/update.
  • Secrets and actor ObjectIDs are not printed.

Installer sequence: privileges → Docker Engine/Compose → arch → manifest → image SHA256 → env bootstrap → actor format → docker load → compose config → host port → iqv-integration-api check → one-shot migrate → compose up -d → live → ready → metadata.

Update / rollback / status / uninstall

bash sudo ./scripts/update.sh sudo ./scripts/status.sh sudo ./scripts/uninstall.sh

Case Behavior
Same image digest/ID NO-OP (container is not restarted)
--force-redeploy Recreate with the same image
New image Transactional update (check → migrate → up → health)
Health FAIL Restore previous immutable snapshot image; metadata of the failed version is not written
Database NOT PERFORMED — external MongoDB is never rolled back or deleted

Default uninstall: compose down, remove API container/network, keep image/env/logs/metadata. --remove-images and --purge are explicit. External MongoDB is never in purge scope.

After host reboot, restart: unless-stopped brings the API back if Docker Engine starts.

Optional auto-update

Default: disabled. Auto-update is not git pull / go build.

Correct model: CI produces a tested immutable release → updater reads a versioned manifest → SHA256/image digest checks → reuses update.sh.

bash sudo AUTO_UPDATE_SOURCE="https://artifacts.example/manifest.json" ./scripts/enable-auto-update.sh sudo ./scripts/disable-auto-update.sh

When AUTO_UPDATE_ENABLED=false, no network request is made. Manual offline package update always works.

Lab-only bundled MongoDB

Repository compose files that include a MongoDB service are development/lab/optional legacy. They are not in the offline production package and are not the recommended production path.

Further reading