# Offline Bundle Install

> Install the Xisom Edge AI Box on an air-gapped site from the offline release bundle — load images, run the installer, set secrets, bring the stack up, and verify health.

This is the recommended way to 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 production edge boxes at a plant or OT site. For a quick
laptop evaluation with internet access, the [Quickstart](/install-deploy/quickstart/)
is faster.

## What you receive

A release bundle is one directory, named for its hardware profile and version
(for example `amd64-cpu-v1.5.0`). Choose the bundle that matches your hardware:

| Bundle profile | Use it when the box has… |
|----------------|---------------------------|
| `amd64-cpu`    | x86_64 CPU, no GPU — CPU-only inference |
| `amd64-gpu`    | x86_64 CPU + NVIDIA GPU — TensorRT acceleration |
| `jetson`       | NVIDIA Jetson (arm64 / L4T) edge module |

Inside the bundle:

- amd64-cpu-v1.5.0/
  - images/
    - amd64-cpu-v1.5.0.images.tar.zst   the three service images, compressed
    - manifest.txt                       image tags + checksums
  - compose/
    - docker-compose.release.yml         image-based stack (no build step)
    - .env.template                      port + secret placeholders
  - models/
    - predictive_maintenance.onnx        demo seed model (random weights)
  - install.sh
  - update.sh
  - uninstall.sh
  - README.txt                           operator one-pager

**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](#install-runbook).

## Before you start

The target box must already have these installed (they ship on the golden OS
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`
- **NVIDIA Container Toolkit** — GPU and Jetson bundles only

Install on a **clean target**. The release stack reuses the same container names,
volumes, and host ports as a development stack — running it on a box that already
has Xisom running will collide.

## Install runbook

1. ### Copy the bundle to the box

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

   ```bash
   cd amd64-cpu-v1.5.0/
   ```

2. ### Run the installer

   The installer auto-detects your hardware profile, loads the container images,
   generates secrets, brings the stack up, and waits for health.

   ```bash
   sudo ./install.sh
   ```

   To force a specific profile, or to also install a boot-start service:

   ```bash
   sudo ./install.sh --profile amd64-cpu   # force the profile
   sudo ./install.sh --with-systemd        # also start on boot
   ```

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

   1. **Preflight** — checks Docker, the GPU toolkit (GPU/Jetson), and disk.
   2. **Verify** the image archive checksum (detects corrupt or tampered media).
   3. **Load images** — `docker load` from the bundled archive (no pull, no build).
   4. **Generate secrets** — creates the JWT signing secret and admin password on
      the box and writes them to a protected `.env` (mode `600`). No secret ever
      ships inside the bundle.
   5. **Start the stack** — `docker compose up -d`.
   6. **Health gate** — waits for all three services to report healthy.
   7. **Seed the admin** and **print the dashboard URL + 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:

   ```bash
   ls -l .env        # expect mode -rw------- (600)
   ```

   If you ever need to provide your own value (e.g. a corporate secret-management
   policy), edit `.env` before the first `up` and set a strong random value:

   ```ini
   # .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
   `predictive_maintenance.onnx` so predictions are meaningful:

   - **Before first install:** overwrite `models/predictive_maintenance.onnx` in the
     bundle, then run `install.sh`.
   - **After install:** drop your model into the model-data volume at `/data/models`
     and restart the inference service.

   You can also upload models later from the dashboard — see
   [Deploying Models](/configure/models/).

6. ### Verify health

   Confirm all three services are healthy:

   ```bash
   docker compose -f compose/docker-compose.release.yml ps
   ```

   Expect three containers in a `healthy` state. Then open the dashboard URL the
   installer printed and sign in with the admin account.

   
**GPU first run is slow**

   On GPU and Jetson profiles, the inference service may sit in `unhealthy` for
   2–3 minutes on first boot while it compiles the TensorRT engine. This is
   expected — wait, then re-check `ps`.
   

## Day-2 operations

  
**Update**

   Deploy a newer bundle. The update snapshots the database first so you have a
   rollback path.

   ```bash
   sudo ./update.sh
   ```

   
**Carry your live .env into the new bundle**

   `update.sh` reads the `.env` from the bundle directory — it holds your
   per-deployment secret, ports, and image references. A freshly downloaded bundle
   has none, so copy the existing install's `.env` into the new bundle directory
   before running the update, or it will abort.
   

   The pre-update snapshot covers the **database only** (not uploaded models or the
   TensorRT cache). Back those volumes up separately if you need to roll models back.

  
  
**Uninstall**

   ```bash
   ./uninstall.sh          # stop the stack, KEEP all data
   ./uninstall.sh --purge  # also delete models + database (confirmation prompt)
   ```

  

## 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` | Wrong bundle profile for this box's CPU. Use the matching profile. |
| `NVIDIA toolkit not wired in` | A GPU/Jetson bundle on a box without the container toolkit. Use the `amd64-cpu` bundle, or fix the GPU stack on the OS image. |
| Inference stuck `unhealthy` | First-run TensorRT compile (GPU) takes 2–3 min — wait. Otherwise check the inference logs. |
| Archive checksum mismatch | Corrupted or tampered USB media. Re-copy the bundle and retry. |

See the full [Troubleshooting](/troubleshooting/) runbook for symptom-keyed fixes.

## Next steps

  - [Connect an input datasource](/configure/input-datasources/) — Stream sensor data into the runtime.
  - [Deploy a model](/configure/models/) — Upload and activate your trained model.
  - [Your first inference](/install-deploy/first-inference/) — Seed a model and see live predictions.