Skip to content

Linux systemd Installation

Production Recommendation

systemd is the recommended native service manager for Linux production environments. Docker is a separate deployment type — see Docker Installation if you prefer containers.

Validation evidence

IMPLEMENTED = YES · AUTOMATED TESTED = YES.
Offline deployment / reboot / NO-OP update: LIVE PASS.
Functional inbound POST: BLOCKED / RETEST REQUIRED (random generated actor ObjectID did not reference an existing user).
Actor/installer fix: IMPLEMENTED / AUTOMATED TESTED / LIVE RETEST REQUIRED.
See Linux systemd E2E.

  • Offline prebuilt Linux amd64 binary package
  • No Go, no source build, no git, no internet, no apt/dnf production dependency install
  • Customer host needs Ubuntu/systemd and an existing MongoDB (often external)

DEVELOPMENT BUILD

  • Go, source tree, tests, and scripts/release/build-linux.sh + scripts/release/package-linux.sh
  • Run only on a development/CI machine — never on the production installer path

Prerequisites

  • Ubuntu 20.04+ or compatible systemd-based Linux distribution (64-bit)
  • MongoDB 6.0+ accessible from this host (installer does not install MongoDB)
  • bash, systemd/systemctl, coreutils (sha256sum, cp, install)
  • sudo / root privileges
  • Offline prebuilt release package (iqv-integration-api-*-linux-amd64.tar.gz)
  • MongoDB URI / database / HTTP port / public base URL for first install (installer creates the runtime env from config/.env.example)
  • No Go, git, or internet on the production host

MongoDB Is a Separate Service

The installer does not install or manage MongoDB. MongoDB must be installed and running before you install IQV Integration API. See your organization's database operations documentation.

Runtime Directory Layout

After installation the service uses these paths:

```text /opt/iqvizyon/iqv-integration-api/ bin/ # Application binary deployment/ # Deployment metadata

/etc/iqvizyon/iqv-integration-api.env # Created by install.sh from package example + CLI (preserved on update)

/var/log/iqvizyon/iqv-integration-api/ # Application logs

/var/lib/iqvizyon/iqv-integration-api/ backups/ # Pre-update backups ```

Installation

1. Run the Installer (from the extracted offline package)

The installer reads config/.env.example and creates /etc/iqvizyon/iqv-integration-api.env (0640, root:iqvapi). An existing file is never overwritten. Optional --env-file PATH still accepts a fully prepared file.

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

Example (lab topology):

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

INTEGRATION_ACTOR_USER_ID is the ObjectID of an existing, active MongoDB user that the integration will use for audit fields. It is not a random ObjectID. The installer never generates one. First-install bootstrap requires --integration-actor-user-id (24-character hexadecimal). --env-file may supply a valid actor instead; an existing runtime env is never overwritten.

Default binary path is ./bin/iqv-integration-api. Override with --binary-path. SHA256SUMS is required; a checksum mismatch does not modify an existing install. Enable auth secrets in the runtime env when AUTH_ENABLED=true.

Secrets

Never log or share the contents of the env file. The installer does not print MongoDB URIs or secret values.

The installer will:

  1. Verify root, systemd, OS/architecture, ELF binary, and SHA256.
  2. Create or preserve the production env (required keys; secrets and actor ObjectID are never printed).
  3. Reject missing/invalid actor format before any deployment mutation.
  4. Create the service user and runtime directories.
  5. Transactionally backup any existing install, then deploy env + prebuilt binary.
  6. Run read-only iqv-integration-api check (MongoDB ping + actor exists/active) before starting the service.
  7. Run migration (unless --skip-migration).
  8. Write/enable/start iqv-integration-api.service (no local mongod.service dependency when --external-mongodb).
  9. Verify /health/live and /health/ready.
  10. Write deployment metadata.

There is no Go download, go build, git, curl, or wget step.

3. Verify

bash sudo systemctl status iqv-integration-api.service

The service should show active (running) status.

```bash

Operator verification (optional; installer already probes without curl)

curl -s http://127.0.0.1:4242/health/live curl -s http://127.0.0.1:4242/health/ready ```

Both endpoints must return HTTP 200 before the installation is considered successful.

Service Management

Status

bash sudo bash ./scripts/linux/service/status.sh

Or directly:

bash sudo systemctl status iqv-integration-api.service

Update

bash sudo ./scripts/update.sh --binary-path ./bin/iqv-integration-api

Same SHA256 → NO-OP. --force-redeploy redeploys anyway. Failed health/start restores the previous binary. Database rollback: NOT PERFORMED. See Update and Rollback.

Uninstall

bash sudo bash ./scripts/linux/service/uninstall.sh

MongoDB Data

The uninstaller never deletes MongoDB data. Your database remains intact after service removal.

Binary Service Commands

The binary itself supports service lifecycle commands:

bash ./iqv-integration-api service install --env-file /etc/iqvizyon/iqv-integration-api.env ./iqv-integration-api service uninstall ./iqv-integration-api service start ./iqv-integration-api service stop ./iqv-integration-api service restart ./iqv-integration-api service status ./iqv-integration-api service run --env-file /etc/iqvizyon/iqv-integration-api.env

The --env-file flag tells the service where to load its environment configuration.

Firewall Configuration

Open the API port (default 8080) using ufw:

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

Or using iptables:

bash sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

Port Conflicts

If port 8080 is already in use, the service will fail to start. Change the port in your env file or stop the conflicting process.

Logging

Application slog is process stdout. systemd captures it in the journal. /var/log/iqvizyon/iqv-integration-api is a writable unit path; the Go process does not write application log files there. Journal:

bash sudo journalctl -u iqv-integration-api.service -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 application cannot reach MongoDB. Verify:

  1. MongoDB service is running: sudo systemctl status mongod.
  2. MONGODB_URI in the env file is correct and reachable from this host.
  3. MongoDB authentication credentials are valid.
  4. Firewall allows outbound connections to the MongoDB port.

Port Conflict (Exit Code 6)

Another process is using the configured port. Find it:

bash sudo ss -tlnp | grep 8080

Migration Failure (Exit Code 14)

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

SHA256 mismatch (exit 8)

The incoming binary does not match SHA256SUMS. The installer refuses to deploy and does not modify the running installation.

Integration actor rejected

First install fails closed when --integration-actor-user-id is missing or is not a 24-character hexadecimal ObjectID. After the binary is staged, read-only check fails if the user does not exist or is not active. Provide the ObjectID of an existing active user. The installer never generates a random actor ID. Database rollback is NOT PERFORMED.

Offline Installation

For air-gapped environments:

  1. On a development/CI machine with Go, run scripts/release/build-linux.sh then scripts/release/package-linux.sh.
  2. Transfer dist/packages/iqv-integration-api-*-linux-amd64.tar.gz to the target (USB, SMB, SCP).
  3. Extract and run sudo ./scripts/install.sh --external-mongodb --mongo-uri ... --mongo-database ... --integration-actor-user-id REAL_USER_OBJECT_ID --port 4242 --public-base-url ....
  4. Ensure MongoDB is reachable from the target host (runtime dependency, not an internet/download dependency).

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 and update scripts automatically verify both endpoints. Do not report success if either probe fails.