Linux CLI installation

This guide installs Heliont on Ubuntu Server (or similar Linux) over SSH with the terminal installer. The same binary is used for updates.

What you will install

Product packs are not downloaded with a browser curl for normal online installs. After you provide a valid license, the installer fetches the entitled pack from the portal. Customers do not pull container images from a public registry.

Before you start (laptop)

1. Sign in to the customer portal and download your license JSON from Licenses.
2. Decide Local (lab / localhost, no certs) or Public (your domain + TLS PEMs).
3. For Public, obtain a full-chain PEM and matching private key that cover every required name — see Obtaining TLS certificates.
4. Optional offline: download the entitled Linux pack (heliont-*-linux-amd64.tar.gz or arm64) from Downloads.
5. Know your CPU architecture:
   • Intel/AMD 64-bit → linux-amd64
   • ARM 64-bit → linux-arm64
6. Confirm you can SSH to the server as a user that can run sudo.

Prepare the server

1. Install Docker Engine and the Compose plugin. Confirm:

docker compose version

1. Create a prep folder (any path you choose) and put the install inputs there:

mkdir -p ~/heliont-prep
cd ~/heliont-prep

Copy files into that folder (for example with scp from your laptop):

• Local online = license only
• Public online = license + TLS PEMs
• Offline = license + pack (+ TLS PEMs if public)

Download the installer

Stay inside the prep folder. Detect architecture, download the latest installer and checksum, verify, then make it executable:

ARCH=$(uname -m)
case "$ARCH" in
  x86_64)  SLUG=linux-amd64 ;;
  aarch64|arm64) SLUG=linux-arm64 ;;
  *) echo "unsupported arch: $ARCH"; exit 1 ;;
esac
curl -fsSL -o "heliont-install-${SLUG}" "https://heliont.store/install/installer/${SLUG}"
curl -fsSL -o "heliont-install-${SLUG}.sha256" "https://heliont.store/install/installer/${SLUG}/checksum"
sha256sum -c "heliont-install-${SLUG}.sha256"
chmod +x "heliont-install-${SLUG}"

No portal login is required for the installer binary. Keep the filename so sha256sum -c matches the checksum sidecar.

Run the installer

You must use sudo. Stay in the prep folder so the current directory contains your license (and optional pack/certs).

Local (typical first install)

sudo ./"heliont-install-${SLUG}"

Public (domain + TLS files in the prep folder)

sudo ./"heliont-install-${SLUG}" -domain heliont.example.com

Replace with your real domain. The installer discovers cert and key files in the current directory.

What the installer does

• Refuses to run without root (sudo)
• Finds the license JSON in the current directory
• Chooses online or offline from whether a pack archive is present
• Chooses local or public from whether TLS PEMs are present
• Installs under /opt/heliont by default
• Prints a setup URL and one-time setup token

Custom install directory

If /opt/heliont is already used for something else on the host, choose another empty directory:

sudo ./"heliont-install-${SLUG}" -install-dir /opt/heliont-app

(Add -domain … for public installs as above.)

Site compose extend (ports behind host nginx)

Stock Heliont publishes host ports 80 and 443. If bare-metal nginx (or anything else) already owns those ports, do not edit compose.yml by hand — updates replace it.

Place one fixed extend file under the install directory (not the prep folder):

<install-dir>/.compose/compose_extend.yml

Example for /opt/heliont-app with Heliont on 7080/7443:

sudo mkdir -p /opt/heliont-app/.compose
sudo tee /opt/heliont-app/.compose/compose_extend.yml <<'EOF'
services:
  webserver:
    ports: !override
      - "7080:80"
      - "7443:443"
EOF

.compose/ and .devconfig/ survive wipe/reinstall and are ignored when checking whether an install folder is empty. Put the extend file in place before first start if ports 80/443 are already taken.

Requires Docker Compose v2 with !override support for replacing the published port list.

Day-2 Compose commands

When you run Compose yourself, include the extend file if you use one:

cd /opt/heliont   # or your -install-dir
sudo docker compose -f compose.yml -f .compose/compose_extend.yml up -d

Alternatively, create /opt/heliont/.env (next to compose.yml) with:

COMPOSE_FILE=compose.yml:.compose/compose_extend.yml

Then plain sudo docker compose up -d merges both files. Listed paths must exist.

Complete web setup

1. Open the printed setup URL in a browser.
2. Enter the setup token when asked.
3. Complete the guided web setup until Heliont reports operational.

Web setup does not upload a license. The installer must already have staged a valid license during install or update.

Flags reference (optional overrides)

Most Linux installs need no flags beyond -domain (public) and optionally -install-dir. Useful overrides:

Troubleshooting

Related documentation

• Installing Heliont — OS overview
• Updating Heliont
• Installing your license file
• Obtaining TLS certificates