Install online

Before you begin

Install LogForge by cloning the public deployment repository and running its installer. It downloads the product images and records the exact release for your installation. No registry login, product source build, or manual image selection is needed.

Use Bash on the server's Linux host, with Git, Docker Engine access, Docker Compose v2, systemd, and internet access to GitHub and the image registries. Check Requirements first. For an isolated server, use Install air-gapped.

This installer currently qualifies native Linux AMD64 Docker hosts. Real ARM hardware qualification remains separate.

1. Get the deployment files

git clone https://github.com/log-forge/unicron-be.git
cd unicron-be

Check: the repository contains install.sh, README.md, compose.yaml, .env.example, and vendor-public.jwks.json. The last file is LogForge's public signing trust, used to verify releases. Keep the installation directory and trust file.

2. Configure before the first startup

Defaults use https://localhost, ports 443 and 9443, local Owner owner, and the clone's data directory. If those settings fit, continue to step 3.

To change them, create your settings file before the first startup:

cp .env.example .env

Open .env in your text editor. For a remote browser or agents on other machines, replace the example hostname with your server's reachable DNS name:

CENTRAL_PUBLIC_URL=https://observability.example.test
CENTRAL_ECHO_PUBLIC_URL=https://observability.example.test
CENTRAL_ECHO_MTLS_PUBLIC_URL=https://observability.example.test:9443
CENTRAL_HTTPS_PORT=443
CENTRAL_MTLS_PORT=9443
CENTRAL_DEPLOYMENT_DNS_NAMES=localhost,observability.example.test
CENTRAL_OPERATOR_LOCALHOST_ENABLED=false

CENTRAL in these literal names means the LogForge server; ECHO means Remote Agent. Keep other supplied entries. For different ports or certificate names, follow Networking and certificates.

To use other storage, set CENTRAL_OPERATOR_DATA_ROOT to a writable absolute Linux path. Later, set DATA to that same path for health and recovery commands. Leaving the setting blank uses ./data.

Second installation on this Docker host: Before startup, set a different CENTRAL_COMPOSE_PROJECT_NAME in .env (for example, logforge-second), a separate data directory, and different HTTPS and agent host ports. The project name keeps each installation's Docker services separate.

Restrict access first: Docker publishes the HTTPS and agent ports on the host's interfaces. localhost is not a firewall. Allow only approved devices and keep internal services private.

Check: the chosen hostname resolves from your browser and agent hosts. Review usage reporting before startup. Runtime secrets are generated automatically; do not add them to .env.

3. Start and check the server

From inside the clone, run:

sudo bash ./install.sh

The installer verifies the published release, starts the required services, configures browser updates and downloads its complete signed image inventory. You do not choose product images or run individual pulls. Keep the terminal open until it reports success. It prints the installed version, HTTPS address, data directory and original source-package path.

Check: the command exits successfully and reports that browser updates are configured. On first success it retains update-package beside the Compose file. Keep that package, the original clone, .env and the data directory. If a failure interrupts initial setup, correct the reported cause and retry the same command. If a product update/recovery operation already exists, use its recorded controls instead; setup refuses to replace that state.

For later checks in an administrator Bash session, set the data path to the installer's output. With default storage:

DATA="$PWD/data"

Do not print, share, or edit deployment.env; it contains generated credentials.

4. Trust HTTPS and create the Owner

1. Find pki/trust/root_ca.crt under DATA.
2. Have your administrator verify and trust this public certificate on your browser machine. Never share private keys or disable certificate checks.
3. Open https://localhost, or your configured CENTRAL_PUBLIC_URL. Set the first password for owner (or CENTRAL_OWNER_USERNAME), then sign in.
4. Open Settings > Account > Usage reporting and save your preference.

Check: LogForge opens without certificate errors. This local Owner is separate from your LogForge website account. See Editions and activation for Business features.

5. Verify readiness and connect an agent

In the same Bash session, match the URL to your settings:

server_url=https://localhost
curl --fail --show-error --silent --connect-timeout 10 --max-time 30 \
  --cacert "$DATA/pki/trust/root_ca.crt" \
  "$server_url/api/v1/health"

Check: readiness.profiles.setup.state is ready or ready_with_advisories; review any advice. Before an agent connects, the operator profile may report required_echo_not_verifiable. Resolve other blockers using reasons, nextActions, and private logs. HTTP 200 alone is not a readiness pass.

Next, connect a Docker host or a supported Kubernetes cluster, then monitor your first workload. After an agent connects, require readiness.profiles.operator.state to be ready or ready_with_advisories and readiness.requiredEcho.state to be current. Check current inventory and fresh workload logs or metrics; retain any readiness advice in your operating record.

After a restart or restore, also confirm the installed version and sign-in, and verify that the existing agent identities and retained telemetry are still present.

Stop, resume, and update

Use Stop and resume safely with the same installation directory and data. These host commands do not configure automatic startup after a VM reboot.

The installer configures Settings > Updates & releases automatically. Manual connected packages can use the one-time server updater setup. After a product update, use the updater's recorded start procedure. Do not rerun the starter Compose file or select product versions with docker compose pull on an existing installation.