Install the Navin Platform from OS packages

This page installs the navin-platform package: the Control Plane API (port 8080), its worker and the portal (port 3300) as hardened systemd services grouped by navin-platform.target, with a local PostgreSQL database. It is done by a system administrator with sudo. Count one hour for a first server, without the OpenBao and Keycloak servers of the bank.

Two ways lead to the same result: the guided installer navin-install (one command, checks first) or the package manager of the system (step by step, below).

Before you begin

• System, checked with cat /etc/os-release:

  • Ubuntu 24.04 (x86_64), package navin-platform_<version>_amd64.deb;
  • RHEL, Rocky, Alma, Oracle Linux or CentOS Stream 9 (x86_64), package navin-platform-<version>-1.el9.x86_64.rpm;
  • Arch Linux (x86_64), package navin-platform-<version>-1-x86_64.pkg.tar.zst.

  Debian, RHEL 8 and RHEL 10 are not supported for the platform package (they are for the node agent): see OS compatibility.

• Rights: an account with sudo; systemd running.

• Resources: 2 CPU, 4 GiB of memory (8 recommended), 20 GiB free for /var, 4 GiB for /opt (Sizing).

• A fully qualified host name that resolves, and a synchronized clock.

• The repositories of the system (or the mirror of the bank): PostgreSQL 15 or newer and Node.js 18.18 or newer.

• Ports 8080 and 3300 free, 9464 for the worker metrics (Network ports).

• For production: an OpenBao server, signing keys in OpenBao, a TLS reverse proxy in front of the API and the portal (TLS).

Option A: guided installer

The offline archive of your family holds navin-install, the packages and their SHA256SUMS.

sha256sum -c navin-install-<version>-<family>.tar.gz.sha256
tar xzf navin-install-<version>-<family>.tar.gz
cd navin-install-<version>-<family>
sudo ./navin-install preflight standalone
sudo ./navin-install standalone --openbao-url https://<openbao-host>:8200 --openbao-token-file /root/openbao.token

<family>: debian (Ubuntu), rhel or arch. <version>: the release, for example 1.0.0.

preflight prints OK, WARN or FAIL per check and changes nothing. standalone installs the system packages, PostgreSQL (local socket only), the Navin Manager (https://<fqdn>:8460), the agent of the host, then the platform. Exit status 0: everything is healthy; 2: the platform waits for its production settings (run navin-platform check, complete them, run the same command again); 1: a failure, with the fix on the screen and the details in /var/log/navin-install.log. --profile evaluation turns the refusals into warnings, for a trial only. The full guide is os/install/README.md.

Option B: package manager

Steps

1. Add the Navin repository. The repository serves the signed packages; without it the package manager cannot find navin-platform. The client files are made by os/repo.sh --sign next to the public key.

   Ubuntu 24.04:

   sudo install -m 0644 navin-archive-keyring.gpg /usr/share/keyrings/navin-archive-keyring.gpg
   sudo install -m 0644 navin.sources /etc/apt/sources.list.d/navin.sources
   sudo apt update

   RHEL family 9:

   sudo curl -fsSo /etc/yum.repos.d/navin.repo https://<repo-host>/rhel/navin.repo
   sudo dnf makecache

   Arch Linux:

   sudo pacman-key --add navin-archive-keyring.asc
   sudo pacman-key --lsign-key <key-fingerprint>
   cat navin.conf | sudo tee -a /etc/pacman.conf
   sudo pacman -Sy

   <repo-host>: host name of the web server (or S3 bucket, Artifactory, Nexus, Satellite, Pulp) where the release manager uploaded the os/repo tree built by os/repo.sh --url https://<repo-host>. It is the same address for apt, dnf and pacman. <key-fingerprint>: fingerprint printed in navin.conf.

   Expected result: apt-cache policy navin-platform, dnf info navin-platform or pacman -Si navin-platform shows the version.

   If it fails: check the proxy of the package manager and that the date of the host is right (signature check).

2. Enable the module streams (RHEL family only). The default PostgreSQL stream of RHEL 9 is 13; the schema needs PostgreSQL 15 or newer and the portal Node.js 18.18 or newer.

   sudo dnf module enable -y postgresql:16 nodejs:20

   Expected result: dnf module list postgresql marks 16 [e].

   If it fails: the AppStream repository is missing from the mirror; add it.

3. Install PostgreSQL and the package. The installation creates the account navin-platform, the venv from the offline wheelhouse of the package, the settings /etc/navin-platform/platform.env with a random master key and the first portal administrator, then the local database when PostgreSQL is present (navin-platform-db local).

   sudo apt install postgresql navin-platform               # Ubuntu 24.04
   sudo dnf install postgresql-server navin-platform        # RHEL family 9
   sudo pacman -S postgresql navin-platform                 # Arch Linux

   Expected result: the last lines print either navin-platform: services started or navin-platform: services enabled, not started: the settings are not complete yet.

   If it fails: the local database could not be configured means PostgreSQL did not start; check systemctl status postgresql, then run sudo navin-platform-db local.

4. Complete the settings. A new host is configured for production (EAI_ENVIRONMENT=prod): the services only start once every production rule holds. List what is missing:

   sudo navin-platform check

   Each line problem: ... names a setting and what is expected. Edit /etc/navin-platform/platform.env (values written KEY='value'); the commented reference is /etc/navin-platform/platform.env.example. The usual additions on a production host:

   EAI_OPENBAO_URL='https://<openbao-host>:8200'
   EAI_OPENBAO_TOKEN='<token>'
   EAI_CONTEXT_SIGNING_KEY_REF='openbao:eai/context#private_key'
   EAI_AUDIT_SEAL_SIGNING_KEY_REF='openbao:eai/audit-seal#private_key'
   EAI_AUDIT_PAYLOAD_KEK='openbao-transit'
   EAI_RAG_EMBEDDING_MODEL='bge-m3-vllm'
   EAI_MEMORY_EMBEDDING_MODEL='bge-m3-vllm'
   NAVIN_PORTAL_API_URL='<control-plane-url>'
   EAI_CORS_ORIGINS='https://<navin-host>'
   EAI_ALLOWED_HOSTS='<control-plane-host>'
   EAI_TRUSTED_PROXIES='10.0.0.10/32'

   <token>: OpenBao token of the platform. 10.0.0.10/32: address of your TLS reverse proxy. Every setting is described in the Configuration reference.

   Expected result: navin-platform check prints navin-platform check: ok.

   If it fails: the line names the setting; a database URL without TLS is fixed by step 5.

   tip

   On a trial host without OpenBao, EAI_ENVIRONMENT='staging' starts the services and only logs the production problems. Never in production.

5. Move the database to the PostgreSQL server of the bank (optional). Production asks for a database URL with sslmode=require, verify-ca or verify-full. The local socket database does not use TLS.

   sudo navin-platform-db external \
     'postgresql://navin_platform:<password>@<pg-host>:5432/navin_platform?sslmode=verify-full' \
     'postgresql://navin_platform_api:<password>@<pg-host>:5432/navin_platform?sslmode=verify-full'

   The first URL is the administrator login (migrations, worker), the second the runtime login of the API (member of eai_runtime, no DDL right).

   Expected result: the migrations run on the new server; sudo navin-platform-db status lists them as applied.

   If it fails: the previous URLs come back. journalctl -t navin-platform-db tells why (without the passwords).

6. Start the services.

   sudo systemctl start navin-platform.target
   systemctl status navin-platform-api navin-platform-worker navin-platform-portal

   Expected result: the three units are active (running). The API applies the pending migrations before each start (ExecStartPre=python -m eai.migrate); the worker refuses to start while one is pending.

   If it fails: journalctl -u navin-platform-api -n 100 shows unsafe production settings: and the broken rules.

7. Enable the media worker (GPU host, optional). navin-platform-media-worker.service is installed but not enabled.

   echo "NAVIN_MEDIA_WORKER_ARGS='--kind stt'" | sudo tee -a /etc/navin-platform/platform.env
   sudo systemctl enable --now navin-platform-media-worker

   Expected result: systemctl status navin-platform-media-worker is active (running).

Verify

curl -fsS http://127.0.0.1:8080/readyz
navin-platform version
sudo navin-platform status

Expected output: "status": "ready", the version of the package and of the Control Plane, and every migration applied. Then open the portal and sign in (First configuration).

Files of the package

Path	Content
/etc/navin-platform/platform.env	Settings of every unit (0640 root:navin-platform), created at the first install
/etc/navin-platform/platform.env.example	Commented reference of the settings, refreshed by the upgrades
/opt/navin-platform/venv	Python venv, rebuilt from the offline wheelhouse at each install or upgrade
/usr/share/navin-platform	Contracts, catalog, SQL migrations (EAI_REPO_ROOT), portal build, wheelhouse
/var/lib/navin-platform	Data and the portal copy with the API URL of the site
/var/log/navin-platform	Writable log folder of the services (they log to the journal: journalctl -u navin-platform-api)
/usr/bin/navin-platform	migrate, status, check, version
/usr/sbin/navin-platform-db	local, external, status, check, migrate

The services run as navin-platform with a read only system (ProtectSystem=strict), no capability, no privilege escalation and a system call filter.

Next steps

• TLS certificates for the reverse proxy
• First configuration
• Upgrade

Troubleshooting

Symptom	Cause	Fix
dnf refuses postgresql-server >= 15	Default module stream 13	sudo dnf module enable -y postgresql:16 nodejs:20
apt cannot install python3.12	Not Ubuntu 24.04	Use Ubuntu 24.04; Debian is not supported for the platform package
pacman refuses a Python upgrade	The package depends on the Python it was built for	Install the Navin release built for the new Python first
navin-platform: ... is not readable	Command run without the group	Run with sudo, or as a member of navin-platform
The portal answers but shows The Control Plane API cannot be reached	NAVIN_PORTAL_API_URL is not the URL of the browsers	Set it, then sudo systemctl restart navin-platform-portal
Worker stays activating	A migration is pending (eai.migrate --check)	sudo navin-platform-db migrate