Offline Bundle Install

This is how you install on a customer edge site with no internet, no registry access, and no image building on the box. You install everything from a single self-contained release bundle that ships on USB media.

When to use this page

Use the offline bundle for every production box. Production runs on the NVIDIA Jetson TX2 only; see Hardware Setup. The laptop demo is for exploring the dashboard, not for deployment.

What you receive

A release bundle is one directory, named for its profile and version, for example jetson-gpu-v1.58.4. The jetson-gpu profile targets the Jetson TX2 on JetPack 4.5 and runs inference on the GPU through CUDA.

Inside the bundle:

• Directoryjetson-gpu-v1.58.4/

  • Directoryimages/

    • jetson-gpu-v1.58.4.images.tar.zst the three service images, compressed
    • manifest.txt profile, version, image tags, checksum
  • Directorycompose/

    • docker-compose.release.yml image-based stack (no build step)
    • docker-compose.tls.yml HTTPS overlay (opt-in)
    • docker-compose.certs.yml datasource TLS cert overlay (opt-in, see below)
    • .env.template port and setting placeholders
  • Directorymodels/

    • predictive_maintenance_op15.onnx demo seed model (random weights)
  • Directorylib/ installer helpers

    • …
  • Directorysystemd/ boot-start unit template

    • …
  • Directorycerts/

    • …
  • Directorytls/

    • …
  • install.sh
  • update.sh
  • uninstall.sh
  • compact-db.sh reclaims database disk space
  • README.txt

The seed model is a demo

The bundled model has random weights. Its predictions are meaningless until you replace it with your trained model. See step 5 of the install runbook.

Where the running stack lives

The installer copies what the running stack needs into /opt/aiboard: the compose files, the seed model, the generated .env, tls/, certs/, and the pre-update backups/. After a successful install or update, the bundle directory is no longer needed by the running box.

Before you start

The target Jetson must already have these installed. They ship on the golden JetPack image. The installer checks for them and stops if anything is missing; it does not install them for you.

• Docker Engine 20.10 or newer, with the docker compose v2 plugin
• zstd and openssl
• The NVIDIA container runtime, registered with Docker
• About 6 GB of free disk where you copy the bundle

Caution

Install on a clean target. The release stack uses the same host ports as a development stack (80, 3000, and 5000). Running both on one box will collide.

Install runbook

1. Copy the bundle to the box

   Copy the whole bundle directory from your USB media to the Jetson, then open a terminal in it:

   cd jetson-gpu-v1.58.4/

2. Run the installer

   The installer detects the Jetson, loads the container images, generates secrets, brings the stack up, and waits for health.

   sudo ./install.sh

   Useful options:

   sudo ./install.sh --profile jetson-gpu   # force the profile
   sudo ./install.sh --with-systemd         # also start on boot
   sudo ./install.sh --no-backup            # skip the pre-migration snapshot (see below)

   Under the hood install.sh runs these steps in order:

   1. Preflight — checks the CPU architecture, Docker, Compose, zstd, openssl, the Jetson and its NVIDIA container runtime, and free disk.
   2. Verify the image archive checksum. This detects corrupt or tampered media.
   3. Load images — docker load from the bundled archive. No pull, no build.
   4. Stage the runtime files into /opt/aiboard.
   5. Generate secrets — creates the JWT signing secret and admin password on the box and writes the secret to /opt/aiboard/.env (mode 600). No secret ever ships inside the bundle.
   6. Snapshot the database — if the box already holds a database, the installer backs it up before the new release can migrate it. See Database snapshots.
   7. Start the stack — docker compose up -d.
   8. Health gate — waits for the services to report healthy.
   9. Seed the admin and print the dashboard URL and admin password once.

3. Save the admin password

   Printed only once

   The installer prints the dashboard URL and the generated admin password a single time at the end of the run. Copy it into your password manager immediately. It is not stored anywhere you can read it back.

4. Confirm the secret was written

   The installer generates the JWT signing secret automatically. You normally never touch it, but you can confirm the protected .env exists:

   sudo ls -l /opt/aiboard/.env   # expect mode -rw------- (600)

   If a corporate policy requires your own value, set it in that file, then re-run sudo ./update.sh from the bundle you installed to apply it. Every signed-in session ends when the secret changes.

   # /opt/aiboard/.env  (placeholder — generate a strong random value, do not reuse)
   AIBOARD_JWT_SECRET=your-strong-random-jwt-secret

5. Replace the demo model

   The bundle ships a demo model with random weights. Replace it with your trained model so predictions are meaningful. Models for the TX2 must use ONNX opset 15 or lower.

   • Upload from the dashboard (recommended). See Deploying Models.
   • Before first install, you can overwrite models/predictive_maintenance_op15.onnx in the bundle. Every update refreshes the seed model from the new bundle, so use the dashboard for a lasting change.

6. Verify health

   Confirm the services are up:

   docker ps --filter name=aiboard- --format 'table {{.Names}}\t{{.Status}}'

   Expect aiboard-inference-real and aiboard-backend-real to show (healthy), and aiboard-frontend-real to show Up. Then open the dashboard URL the installer printed and sign in with the admin account.

   First start takes a moment

   The inference service initialises CUDA on first start. Its health check allows a 90-second start period, so it shows starting for up to about a minute and a half. This is expected. Wait, then re-check.

Day-2 operations

Update

Deploy a newer bundle. Copy it to the box, open a terminal in it, and run:

sudo ./update.sh

update.sh reads the live configuration from /opt/aiboard/.env, so you do not copy anything between bundle directories. It then:

1. Snapshots the database with its writers stopped, and verifies the archive. See Database snapshots.
2. Loads the new images and points the configuration at them.
3. Recreates the stack. The backend migrates the database on start.
4. Waits for health. If the stack does not become healthy, the update stops, prints how to roll back, and removes nothing.
5. Cleans up, only after the new release is healthy:
   • It keeps the newest AIBOARD_BACKUP_KEEP snapshot archives (default 3) and removes older ones. Set AIBOARD_BACKUP_KEEP=0 in /opt/aiboard/.env to keep every archive. See Environment Variables.
   • It keeps the images of the release it just installed and the release it replaced, and removes older Xisom images. When you re-run the same release, for example after a failed health gate, it skips image cleanup so the previous release stays available for rollback.

To skip the snapshot, pass --no-backup. Only do this if you took a snapshot by other means: database migrations are forward-only.

Installed before /opt/aiboard existed?

An older install keeps its .env inside a bundle directory. update.sh stops and asks you to move it once with sudo ./update.sh --migrate. That copies .env (so the JWT secret and every session survive), tls/, and certs/ into /opt/aiboard. It deletes nothing.

Uninstall

sudo ./uninstall.sh          # stop the stack, KEEP all data
sudo ./uninstall.sh --purge  # also delete the database, models, and logs (confirmation prompt)

Database snapshots

Both install.sh and update.sh back up the database before a new release can migrate it:

• The snapshot is taken with the database’s writers stopped, so the archive is consistent. The stack starts again when the run continues; if the run fails before that point, the stopped containers are restarted.
• The archive is read back before anything else changes. If it does not read back, the run stops while the current database is still untouched.
• Archives are written to /opt/aiboard/backups/ as backup-<UTC timestamp>.tgz. The run prints the exact restore command next to the archive name.
• A snapshot covers the database only, not uploaded models. Back up the model volume separately if you need to roll models back.
• --no-backup skips the snapshot on either script.

Datasource TLS certificates

Datasource-side TLS — the CA, client certificate, and key an MQTT or OPC UA datasource uses to reach a secured broker or server — is separate from the box’s own HTTPS certificate. It is off by default. Turn it on with a .env flag, symmetric with AIBOARD_TLS_ENABLED:

/opt/aiboard/.env

AIBOARD_CERTS_ENABLED=1

Put your MQTT/OPC UA CA and client certificate/key files in /opt/aiboard/certs/. When the flag is on, the installer and update.sh layer the bundled docker-compose.certs.yml overlay on top of the release stack, and the backend mounts that directory read-only. Before the first install, set the flag in the bundle’s compose/.env.template instead. On a running box, re-run sudo ./update.sh after you change the flag.

Cert paths are server-side and jailed

A datasource’s cert-path fields (CA file, client cert, client key) resolve on the backend container’s filesystem, confined to the mounted certificate root — not a path on the operator’s own machine. See Connecting Datasources and Output Datasources for where to set them.

Updates keep your certificates

Certificates can’t be regenerated the way the box’s own TLS certificate can. /opt/aiboard/certs/ belongs to no bundle, so an update leaves it as it is. On an older install that kept certificates inside a bundle, update.sh copies them into /opt/aiboard/certs/ first.

uid 1001 must be able to read the certificates

The backend container reads cert files as uid 1001. Set ownership and permissions on /opt/aiboard/certs/ (and every file inside it) so uid 1001 can read them. Otherwise the datasource fails to load the certificate when it connects.

If something goes wrong

Symptom	What it means
Bundle manifest missing	You ran the installer from a source folder, not an assembled bundle. Use the bundle directory you copied from USB.
Architecture mismatch	The bundle is for an arm64 Jetson, and this machine is not one. Copy the bundle to the Jetson.
/etc/nv_tegra_release is absent	The machine is not a Jetson running L4T. Install on the Jetson TX2.
NVIDIA container runtime not wired into Docker	Docker on this Jetson has no nvidia runtime. Fix the JetPack image so Docker lists it.
Low disk	Not enough free space for the images. Free about 6 GB and retry.
Inference shows starting	CUDA initialisation takes up to about 90 seconds on first start — wait. If it then turns unhealthy, check docker logs aiboard-inference-real.
Found an existing install at: …	The box was installed before /opt/aiboard existed. Run the same script once with --migrate.
Archive checksum mismatch	Corrupted or tampered USB media. Re-copy the bundle and retry.

See the full Troubleshooting runbook for symptom-keyed fixes.

Next steps

Connect an input datasource Stream sensor data into the runtime.

Deploy a model Upload and activate your trained model.

Your first inference Seed a model and see live predictions.