Offline / Air-Gapped Deployment

TracePcap is designed to support fully offline operation. This page covers the workflow for deploying to a machine that has no internet access.

Note

Geolocation behaviour: By default, TracePcap attempts to enrich external IPs using ipinfo.io when internet access is available. On an air-gapped machine it automatically falls back to the bundled DB-IP Lite MMDB — no configuration change is needed. All other features (packet parsing, nDPI, session reconstruction, file extraction, custom signatures) are fully offline at all times.

If you want to force MMDB-only lookups even on an internet-connected machine, remove internet access from the container. If the MMDB file is not at the default location, also set the GEO_MMDB_PATH environment variable (or tracepcap.geo.mmdb-path in application.yml).

Overview

  1. On an internet-connected machine: pull all images and save them as .tar files.

  2. Transfer the tarballs (plus a few scripts) to the offline machine.

  3. On the offline machine: load the images and start the stack.

Step 1 — Pull and Save Images (online machine)

bash scripts/pull-and-save-images.sh

This creates an images/ directory containing .tar files for every service (backend, frontend, postgres, minio, nginx, …).

Step 2 — Transfer Files to the Offline Machine

Copy the following to the offline machine (USB drive, SCP, etc.):

images/                        # all .tar image archives
docker-compose.offline.yml
scripts/load-images.sh
.env                           # copy from .env.example and configure first

Step 3 — Load Images and Start the Stack (offline machine)

# Load all images into Docker
bash scripts/load-images.sh

# Start the stack using the offline compose file
docker compose -f docker-compose.offline.yml up -d

LLM Configuration for Offline Use

AI features (Story Mode, AI Filter Generator) require an OpenAI-compatible inference server. The offline compose file defaults to:

LLM_API_BASE_URL=http://localhost:1234/v1

Configure a locally-hosted LLM (e.g. LM Studio or Ollama) and set LLM_API_BASE_URL in your .env before starting. See LLM Setup for details.

Note

If no LLM server is available, TracePcap works fully without AI features — only Story Mode and AI Filter Generator will be non-functional.