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 Piece What it is How you get it Heliont Installer (heliont-install) Free binary that installs and updates Heliont Curl from the portal (no login) — always the latest build for your OS/arch License JSON Entitles your installation to product packs Licenses while signed in, then copy to the server Docker Engine + Compose Runs the Heliont containers Install on the server before running the installer Optional offline pack Signed heliont-*-linux-*.tar.gz when the server cannot reach the portal Downloads while signed in Optional TLS PEMs Full-chain certificate + private key for Public publishing Your CA / Let’s Encrypt — see TLS certificates
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)
- Sign in to the customer portal and download your license JSON from Licenses.
- Decide Local (lab / localhost, no certs) or Public (your domain + TLS PEMs).
- For Public, obtain a full-chain PEM and matching private key that cover every required name — see Obtaining TLS certificates.
- Optional offline: download the entitled Linux pack (heliont-*-linux-amd64.tar.gz or arm64) from Downloads.
- Know your CPU architecture:
- Intel/AMD 64-bit → linux-amd64
- ARM 64-bit → linux-arm64
- Confirm you can SSH to the server as a user that can run sudo.
Prepare the server
- Install Docker Engine and the Compose plugin. Confirm:
docker compose version
- 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):
File When License .json Always fullchain.pem + privkey.pem (those names preferred) Public only heliont-*-linux-….tar.gz Offline only
- 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 Path Role compose.yml Stock product file; installer replaces on update .compose/compose_extend.yml Site extend; installer always merges when present .devconfig/* Manual/dev overlays only; installer never auto-loads these
.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
- Open the printed setup URL in a browser.
- Enter the setup token when asked.
- 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:
Flag Purpose -domain Public primary domain (required when TLS PEMs are present) -install-dir Host install path (default /opt/heliont) -license Explicit license path (otherwise discovered in cwd) -pack Explicit offline pack path -mode online|offline Force mode instead of inferring from pack presence -agree-license Accept license terms without a prompt (with -yes) -yes Non-interactive defaults -branch install|update|uninstall Force branch (interactive menu when omitted) Troubleshooting Symptom What to check Exec format error Wrong arch binary (amd64 vs arm64) run with sudo… Run the installer with sudo no valid Heliont license JSON found in this folder License not in the current directory, or verification failed — re-download from Licenses address already in use on port 80/443 Host nginx owns those ports — add .compose/compose_extend.yml, then start again install directory is not empty Choose a free path with -install-dir, or wipe/update an existing Heliont install Certificate / domain errors Public needs matching PEMs in the prep folder plus -domain Curl installer 503 / empty file Confirm https://heliont.store/install/installer/linux-amd64 returns HTTP 200 Related documentation