Install, Upgrade, and Rollback

PacketSafari on-prem is installed and upgraded from the host, not from the browser UI.

For the full host-side command reference, see PacketSafari Ops CLI.

Host prerequisites

Use Ubuntu Server 24.04 LTS or newer. Before installing or upgrading, ensure the host has:

• Docker and the Docker Compose plugin
• curl
• python3
• tar
• zstd
• openssl
• network access to the authenticated release URLs for connected installs, or local/USB access to the offline bundle
• write access to the managed runtime root, which defaults to /opt/packetsafari
• enough disk for bundle extraction, image load, database, captures, and rollback snapshots

Minimum single-node sizing for test and small deployments:

• 4 vCPU
• 16 GiB RAM
• 120 GiB root or data volume
• host architecture matching the release artifact, for example linux-arm64 requires an ARM64 host

Install the host packages:

sudo apt-get update
sudo apt-get install -y docker.io docker-compose-v2 zstd tar openssl curl python3
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Log out and back in after adding the user to the docker group, or run deployment commands with sudo.

Expose only the ports required for the deployment boundary:

• 22/tcp for operator SSH
• 3000/tcp for the PacketSafari frontend if accessed directly
• 8080/tcp for backend health/API if accessed directly
• 4448/tcp for direct browser-to-sharkd WebSocket traffic

The frontend intentionally connects directly to sharkd for low-latency packet views. If DNS, NAT, or a load balancer changes the externally reachable sharkd address, set NUXT_PUBLIC_SHARKD_WS_URL to that explicit ws:// or wss:// URL.

Corporate outbound proxy

Some customer networks require all outbound HTTP and HTTPS traffic to pass through an enterprise proxy such as Zscaler.

Configure that proxy on PacketSafari's egress proxy service, not on the application containers directly. Backend and worker containers should continue to use PacketSafari's internal egress-ironproxy endpoint so allowlisting, egress logs, and upstream secret isolation remain intact.

Set the upstream proxy values supplied by the customer network team:

/opt/packetsafari/bin/packetsafari-ops config upstream-proxy \
  --proxy-url http://zscaler-proxy.customer.example:8080 \
  --no-proxy localhost,127.0.0.1,::1 \
  --restart

This writes /opt/packetsafari/env/ironproxy.env and restarts only egress-ironproxy.

Do not set PACKETSAFARI_EGRESS_PROXY_URL to the corporate proxy. That value controls where backend and worker send monitored egress, and it should normally remain http://egress-ironproxy:10000.

If the corporate proxy performs TLS inspection, install the customer root CA under the PacketSafari custom CA directory before restarting egress-ironproxy:

sudo install -d -m 0755 /opt/packetsafari/configuration/custom-ca
sudo cp /path/to/customer-root-ca.crt /opt/packetsafari/configuration/custom-ca/customer-root-ca.crt
/opt/packetsafari/bin/packetsafari-ops diagnostics restart --service egress-ironproxy

PacketSafari supports standard HTTP proxy chaining through HTTP_PROXY and HTTPS_PROXY. PAC files, NTLM/Kerberos proxy authentication, and SOCKS-only proxies require a customer-side HTTP proxy bridge or additional product work.

Fresh install

Use the bootstrap entrypoint:

curl -fsSL https://raw.githubusercontent.com/oripka/packetsafari-onprem/main/bootstrap.sh | bash -s -- install --license /path/to/license-token.json --manifest ./release-manifest.json --size auto

Fresh installs require a release manifest generated from the app repo:

cd /Users/otr/code/packetsafari
node scripts/release_packetsafari.mjs --manifest-out ./release-manifest.json

What happens during install:

1. The bootstrap script downloads the full on-prem tooling bundle.
2. The bootstrap shim verifies the packaged Python CLI checksum.
3. The license token is verified against the bundled public key.
4. The Python operator bundle is installed under /opt/packetsafari/tooling/onprem, including its own self-managed Python runtime, and exposed through /opt/packetsafari/bin/packetsafari-ops.
5. PacketSafari renders a digest-pinned compose file under /opt/packetsafari/compose/.
6. PacketSafari writes an automatic sizing profile unless --size none is selected.
7. The runtime env and deployment state are written under /opt/packetsafari/.
8. Docker Compose starts the stack in onboarding mode.

After the containers are up, the preferred operator path is:

/opt/packetsafari/bin/packetsafari-ops tui

The browser onboarding flow remains available as a fallback.

The terminal operator interface is a simple menu runner with back navigation, not a full-screen terminal dashboard.

Fresh installs now also seed audit logging defaults into runtime.env so enterprise customers start with persisted security audit events and JSON stdout forwarding semantics.

If the VM is resized later, run:

/opt/packetsafari/bin/packetsafari-ops tune --profile auto --apply

That regenerates the managed sizing env and compose override, then recreates the stack with the new limits.

License claims

The installed license token is a signed offline entitlement. PacketSafari verifies the signature locally and normalizes these claims:

Agent reports include watermark metadata with the report ID, capture ID, deployment mode, customer ID, deployment ID, support tier, and license fingerprint. The watermark is intended for provenance and support traceability, not for embedding secrets.

A focused standard-model run costs one unit. Fast + verification and a focused strongest-model run cost two; deep investigation on the strongest model costs four. Issue separate entitlement tokens for the production and non-production licensed deployments; do not reuse a deployment identity across both.

Native onboarding checklist

After the host-side install finishes, the operator should complete onboarding in the terminal menu:

1. Launch /opt/packetsafari/bin/packetsafari-ops tui.
2. Open Onboarding and load the local onboarding schema.
3. Confirm the release manifest and license state shown in the terminal summary.
4. Fill the required deployment values, especially mail delivery, audit logging, AI provider, and identity settings.
5. Leave generated-capable internal secrets blank if you want PacketSafari to generate them during finalize. Provide manual values for external credentials such as SMTP, shared AI provider keys, OIDC client secrets, and SCIM bearer tokens.
6. If the deployment will use a local or OpenAI-compatible model server, set the provider type, base URL, and auth mode before validating.
7. If that base URL points to another host on the customer network or the internet, save it first and run the approval command shown in the admin AI settings UI before using Test connection.
8. Use Validate to confirm the required env keys are present.
9. Select Finalize onboarding, then restart the stack if PacketSafari reports that a restart is required.
10. Create the initial administrator from inside the backend container using the bootstrap command shown in the TUI or login page.

Create the first administrator from inside the backend container:

docker exec -it backend python3 /app/scripts/create_initial_admin.py --username packetsafari --email admin@example.com

The script prompts securely for the password and only works while no administrator exists yet. The login page also shows this command until the first admin has been created. After bootstrap, administrators can continue user setup according to the deployment's local auth or enterprise identity configuration.

The onboarding flow writes the managed runtime.env and flips the deployment out of onboarding mode for the next restart. Initial administrator creation happens afterward from inside the backend container.

For the full local/on-prem model workflow, including external AI host approval and the runtime security model, see Local models and external AI approval.

Quick troubleshooting after onboarding

If AI settings save successfully but model testing or inference still fails:

1. confirm the selected provider/auth mode matches the intended deployment
2. if using shared OpenAI environment auth, confirm OPENAI_API_KEY was provided during onboarding
3. if using another host on the customer network or the internet, confirm the host approval command was run
4. if using HTTPS with a private CA or self-signed certificate, add that CA to the PacketSafari egress proxy trust store
5. restart the stack after finalize so the new managed runtime.env is active

Upgrade

Place the new release manifest on the host, then run:

curl -fsSL https://raw.githubusercontent.com/oripka/packetsafari-onprem/main/bootstrap.sh | bash -s -- upgrade --manifest ./release-manifest.json

During upgrade, PacketSafari:

• validates the installed license token
• checks the current runtime.env against the target manifest's requiredEnv
• snapshots the current manifest, runtime env, deployment state, and compose file into /opt/packetsafari/backups/
• renders the target compose file
• restarts the stack with the new release

If the target release requires new configuration keys, provide them before running the upgrade.

Rollback

Rollback restores the most recent backup snapshot:

curl -fsSL https://raw.githubusercontent.com/oripka/packetsafari-onprem/main/bootstrap.sh | bash -s -- rollback

Rollback restores:

• the previous release manifest
• the previous runtime env
• the previous deployment state
• the previous rendered compose file

After restoring those files, the stack is restarted with the previous version.

Inspecting deployment state

Useful host-side checks are:

/opt/packetsafari/bin/packetsafari-ops status --json

ls -lah /opt/packetsafari/backups

cat /opt/packetsafari/state/deployment-state.json

For the complete command list, sizing behavior, and runtime file reference, see PacketSafari Ops CLI.