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, set GEO_FORCE_OFFLINE=true (see below). 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).

Suppressing Runtime Egress (`GEO_FORCE_OFFLINE`)

The ipinfo.io geolocation enrichment is the one intentional runtime egress in TracePcap. By default the backend probes ipinfo.io (~every 60s while resolving new external IPs) and uses it when reachable, falling back to the bundled MMDB otherwise. The fallback is graceful, but the outbound attempt still occurs.

For strict air-gapped or egress-monitored deployments, set:

GEO_FORCE_OFFLINE=true

When enabled, TracePcap:

never performs the connectivity probe or any ipinfo.io lookup — no outbound ipinfo.io connection is attempted (verifiable via egress logs / a firewall deny rule), and
resolves geo exclusively from the bundled DB-IP Lite MMDB (geo_source = mmdb on every result).

This is the recommended setting for the offline compose stack. With it set, TracePcap makes no external network calls at runtime (aside from a locally-hosted LLM server, if configured — see below).

Overview

On an internet-connected machine: pull all images and save them as .tar files.
Transfer the tarballs (plus a few scripts) to the offline machine.
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.