Skip to content

Offline installation

For servers without outbound internet. You need a second machine with internet to fetch the offline package.

Package contents

vesana-vX.Y.Z-offline.tar.gz contains:

  • All Docker image tarballs
  • docker-compose.prod.yml
  • setup.sh
  • .env.example
  • Agent and collector binaries (Linux + Windows)
  • Compose-file manifest and migrations directory

Step 1 — Get the package

On a machine with internet:

  • Variant A: licence portal → Downloads → Offline package
  • Variant B: Existing online instance: Admin → Updates → „Download offline package"

Step 2 — Transfer to server

# e.g. via USB stick
mount /dev/sdb1 /mnt/usb
cp /mnt/usb/vesana-vX.Y.Z-offline.tar.gz /opt/
umount /mnt/usb

Or via scp from a network segment that can reach the server.

Step 3 — Extract

sudo mkdir -p /opt/vesana && cd /opt/vesana
sudo tar xzf /opt/vesana-vX.Y.Z-offline.tar.gz

Step 4 — Load Docker images

for img in images/*.tar; do
  echo "Loading $img ..."
  sudo docker load < "$img"
done

Images are now available locally. docker compose pull would fail — but isn't called in the offline workflow.

Step 5 — Configure

sudo ./setup.sh --offline

Offline variant skips network steps and expects images already loaded.

Or manually:

sudo cp .env.example .env
# edit .env — passwords, SECRET_KEY, FIELD_ENCRYPTION_KEY, BASE_URL, REGISTRY_URL
sudo docker compose -f docker-compose.prod.yml up -d

Step 6 — Run wizard

Open browser on a machine on the same network:

https://<server-ip>

If using a self-signed cert, accept the browser warning. For clean TLS: mount your own cert into the nginx container — see TLS / reverse proxy.

Offline license activation

Online licenses need a phone-home to license.vesana.org, which isn't reachable in air-gapped networks. Instead:

  1. In the licence portal: Licenses → Create offline license
  2. Provide customer UUID and tier
  3. Download the generated <customer>-license.json
  4. Transfer via USB to the server
  5. In Vesana: Admin → License → Upload offline license

Offline licenses have a duration (typically 1 year) and must be renewed before expiry — the server warns 30 days ahead via banner.

Offline updates

Updates also come as offline packages. Workflow is identical to first install:

# On internet machine:
license.vesana.org → Releases → Download update package

# On server:
scp vesana-update-vX.Y.Z.tar.gz root@server:/opt/vesana/

# In admin UI:
Admin → Updates → Upload offline package → Start update

Details: Updates → Offline update.

What doesn't work offline

Feature Impact
Update check No automatic notification of new versions — check at vendor manually
Mobile push (shared FCM) Doesn't work — you need your own Firebase project with a reachable endpoint
Cloud AI Anthropic / external APIs unreachable — only local Ollama works
Wiki web search No DuckDuckGo queries — only RAG from the wiki

Next