Install air-gapped

Before you begin

Use this guide when your LogForge server cannot reach the internet. The complete signed release bundle supplies the server's container images. For a host with internet access, use Install online.

Both methods run in your own infrastructure, including on premises. Air-gapped means the installation is isolated from the public internet; your browser and Remote Agents still need approved internal connections to the server.

You need Bash and Docker access on a supported Linux host, the Compose plugin, durable storage, and an approved file-transfer method. Check Requirements.

Prepare the whole deployment: the bundle starts the server without image downloads. It does not automatically distribute images to separate Docker hosts or Kubernetes nodes. First agent installation still pulls its exact image; preloading alone does not replace that step. Obtain a release-approved disconnected installation procedure. Later agent updates have a separate internal-registry setup.

Prepare files and network access

On a connected machine, obtain the complete signed release and its independently supplied vendor public verification file from LogForge. A public key found only inside the archive does not establish its publisher.

For the published October 28 release, choose the server's CPU:

Use uname -m on the server to check. Confirm approval for your target hardware with LogForge. A Docker Hub component or release-metadata image alone is not the complete offline installer.

Transfer the unchanged bundle and verification material through your approved process. Keep the original for recovery. Install required host tools through your organization's offline software process.

Before startup:

• Choose an internal hostname or IP address reachable from approved browsers and agent hosts.
• Allow only the chosen HTTPS and agent ports. Keep other services private.
• Enforce your outbound restrictions. Usage reporting is on by default and has no pre-start file switch; turn the saved preference off after sign-in if required.
• Arrange consistent backups and enough storage for saved logs and metrics.

Extract and configure the package

In Bash on the server's Linux host, from the transferred bundle's directory, use the matching archive. This example is AMD64:

tar -xf unicron-2026.10.28.53-linux-amd64-offline.tar
cd unicron-2026.10.28.53
sha256sum -c SHA256SUMS

Check: every checksum passes. The launcher also verifies the signature and CPU against your independent verification file; checksums alone do not identify the publisher. Confirm images.tar, IMAGE_LOCK, and offline-import-images.sh are present. Stop if verification fails or files are missing.

Before the first startup, edit the supplied operator.env. For example, replace the hostname and storage path below with your own:

UNICRON_PUBLIC_URL=https://observability.example.test
UNICRON_ECHO_PUBLIC_URL=https://observability.example.test
UNICRON_ECHO_MTLS_PUBLIC_URL=https://observability.example.test:9443
UNICRON_DATA_ROOT=/srv/unicron

ECHO in these literal setting names means Remote Agent. The first URL is for your browser, the second for agent setup, and the third for agent connections authenticated with certificates. The first two URLs share the HTTPS port; their hostnames may differ when configured before startup. The third uses a separate port. See the local-browser and remote-agent example.

Keep the original signed archive beside the extracted directory: first updater setup uses it to recover the signed baseline after settings are edited. Prepare a writable, absolute storage path. For other ports, local-only defaults, and exact file rules, see Installation settings. Do not add settings or generate secrets yourself.

Restrict access first: Docker publishes ports on the host's interfaces. localhost is not a firewall. Apply network or Docker-aware host restrictions before starting.

Start and check the server

Stay inside the extracted directory. Replace the verification-file path:

./unicron up --trust /absolute/path/to/vendor-public.jwks.json
./unicron status

The launcher verifies and imports bundled images, creates private settings, and starts services without pulling server images. It prints the browser URL.

Check: long-running services stay running and become healthy. Initialization services may finish successfully and exit. For failures, read logs privately:

./unicron logs

Fix the reported cause and retry the same trusted startup command with the same data root. Do not remove the bundle's images or bypass verification to work around errors.

Trust HTTPS and create the Owner

1. Locate pki/trust/root_ca.crt under your configured data root. The default for UNICRON_DATA_ROOT=auto is $HOME/.local/share/unicron.
2. Have your administrator verify and trust this public certificate on your browser machine. Never distribute private keys or disable certificate checks.
3. Open the printed HTTPS URL and set the first password for local owner, then sign in. Your LogForge website account is separate.
4. Open Settings > Account > Usage reporting and save the required reporting preference.

Community needs no activation key. Business features use Offline activation: transfer the installation's request to your authorized license administrator, then import the matching signed response. Do not enable internet access just to activate.

Verify product readiness

In Bash on the server host, set these variables to match operator.env, including any custom port:

server_url=https://observability.example.test
data_root=/srv/unicron
curl --fail --show-error --silent --connect-timeout 10 --max-time 30 \
  --cacert "$data_root/pki/trust/root_ca.crt" \
  "$server_url/api/v1/health"

Read readiness.profiles.setup and readiness.profiles.operator:

HTTP 200 is not a readiness pass. It only means the report loaded. Do not use -k to skip a certificate error.

After connecting an agent, check saved logs and metrics and repeat the readiness check. Require operator ready or ready_with_advisories.

Stop, resume, and update

Keep the installation directory, data root, original archive and independent verification file. Follow Keep your deployment data for safe stops and restarts. After the native updater has adopted an installation, preserve its containers; the old remove-and-recreate restart is refused.

Use Settings > Updates & releases > Upload update file for the unchanged approved update archive. See Updates and recovery for server-first ordering, agent updater setup and explicit recovery. Do not create a new data root or agent identity to repair an existing installation.