Back to the home page

Installation guide

Installing KERNOVIQ with one command: requirements, the demo and the full package, verifying the installer before running it, options and troubleshooting.

KERNOVIQ runs on your own Linux machine or server. With internet access, one command installs it; servers without internet access use the offline bundle instead (airgap.md). On a Windows server or PC, a setup program installs it in WSL 2 (see Windows below). All three install the same product: without a licence key it runs as the restricted trial edition, and a key entered in Settings → Licence lifts every restriction in place (licensing.md).

Package For What you get
Demo (default) trying KERNOVIQ HTTPS on the network, at this machine's name and at its IP addresses (internal CA); the services a trial uses; a one-time link to create the first administrator in the browser
Full a server for the organization, with a licence the full edition: HTTPS on the internal network, at the server's name and at its IP addresses (internal CA or your certificate), every service including the scan runner, start at boot and daily encrypted backups (as root)

Both reach the other devices on the network: colleagues open the server's name or its address (https://192.168.1.20). --local keeps an installation to the machine itself instead (http://127.0.0.1:8280, nothing on the network).

The demo package is the trial build and is free to download. The full package is the full build: the installer fetches it from the licence server with your licence key (licensing.md).

Requirements

  • Linux on x86-64, 4 GB of memory (8 GB for the full package with many users), 10 GB of free disk space
  • Docker Engine with the Compose plugin, or Podman 4+ with docker-compose (rootless Podman: systemctl --user enable --now podman.socket)
  • bash 4.4+, curl, tar, sha256sum, ssh-keygen (OpenSSH 8.1+) — present on current distributions
  • outbound HTTPS to kernoviq.org and to the image registry named in the release

Demo

curl -fsSL https://kernoviq.org/install.sh | bash

The installer checks the machine, downloads the release, verifies it and starts KERNOVIQ, then prints where it answers — this machine's name and its addresses, e.g. https://192.168.1.20 — and a link like https://<name>/setup#token=… (with the same link at the address, for a device that does not know the name). Open it, create your organization and the first administrator, and you are in. The link works once; keep it to yourself until then.

The certificate comes from an internal CA the installation creates, so browsers warn about it until they trust that CA: confirm the warning, or import kernoviq-ca.crt from the installation directory on the devices you use. The certificate names the machine's addresses; when the address changes (DHCP), kernoviqctl start adds the new one, and kernoviqctl cert renew does so at any time. If a firewall on the machine or the network filters incoming connections, let TCP 443 (and 80, which redirects to HTTPS) through.

As a user with rootless Podman or in the docker group the installation goes to ~/.local/share/kernoviq; with sudo to /opt/kernoviq. Rootless Podman listens on 8443 and 8080 instead of 443 and 80; --https-port and --http-port pick others, --server-name another name. With --local KERNOVIQ answers at http://127.0.0.1:8280 on this machine only (--port 8380 picks another port).

Full package on a server

curl -fsSL https://kernoviq.org/install.sh | sudo bash -s -- --edition full --server-name kernoviq.example.internal \
  --license-key-file /root/kernoviq-licence.txt

The licence file holds the key from the licence e-mail (KQL1…). The installer sends it with the version to the licence server (https://license.kernoviq.org, or --license-server URL), which answers with the full kit and a credential for its images that expires within hours; the kit is checked against the licence server's checksum and against the signed list of the release, and the key is activated once KERNOVIQ runs. A key the licence server refuses (not accepted, revoked, ended, outside its period of updates) stops the installation before anything changes, also with --dry-run.

It asks for the organization and the first administrator (or pass --org, --admin-email, --admin-name, --admin-password-file, or --web-setup for a browser link), creates an internal CA and a server certificate (or uses yours: --cert FILE --key FILE [--ca FILE]), and enables the kernoviq systemd service and the nightly encrypted backup. Distribute /opt/kernoviq/kernoviq-ca.crt to the users' computers when you use the internal CA. Users reach the server at its name or, where DNS does not know it yet, at its address. Day-to-day operation — certificates, backups, upgrades, runners, internal systems — is the same as for the offline bundle (airgap.md, from section 4).

Windows

On Windows 10 22H2, Windows 11 and Windows Server 2022 or newer (64-bit), download KERNOVIQ-Setup.exe from the KERNOVIQ site and run it as an administrator. It needs hardware virtualization, 6 GB of memory (8 GB recommended) and 20 GB of free disk; domain controllers are not supported.

The wizard turns on WSL 2 if needed (after a restart it continues by itself), creates KERNOVIQ's own Ubuntu distribution with Docker Engine, and serves KERNOVIQ to the network over HTTPS under the DNS name you give, with an internal CA or your organization's certificate. It ends with a one-time link for the first administrator. KERNOVIQ starts with Windows, without anyone signed in, and is operated with the kernoviq command (kernoviq status, doctor, backup, upgrade). Upgrade by running a newer setup program; uninstall in Settings → Apps (the backups stay).

Unattended:

KERNOVIQ-Setup-<version>.exe /S /ACCEPT_EULA /SERVERNAME=kernoviq.example.internal

Everything else — what it sets up on Windows, users and certificates, backups, troubleshooting — is in the Windows guide.

Read before you run

The installer is a single bash script. To read it first, and to check the release yourself:

curl -fsSLO https://kernoviq.org/install.sh
less install.sh
version=$(curl -fsSL https://kernoviq.org/releases/latest)
for file in SHA256SUMS SHA256SUMS.sig release-signer.pub; do curl -fsSLO "https://kernoviq.org/releases/$version/$file"; done
printf 'kernoviq-release namespaces="kernoviq-bundle" %s\n' "$(cat release-signer.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I kernoviq-release -n kernoviq-bundle -s SHA256SUMS.sig < SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS      # install.sh: OK
ssh-keygen -l -f release-signer.pub           # compare with the fingerprint on kernoviq.org
bash install.sh

What it does, in this order: checks the machine (operating system, tools, container engine, memory, disk, the port); downloads the release's checksum list and verifies its signature against the KERNOVIQ release key written into the script; downloads the kit (compose files, kernoviqctl, documentation — a few hundred kilobytes; the full package's from the licence server, for the licence key) and checks it against the verified list; runs kernoviqctl install, which pulls the images by the digests the signed kit names (the container engine checks every layer against them), creates settings, keys and certificates and starts the services; prints the setup link.

What it never does: send anything about you or the machine anywhere (the full package sends the licence key and the version to the licence server), set a password of its own, open ports to the network (unless you ask for HTTPS with --server-name), or start a scan. --dry-run stops after the checks and the verification.

Options

Option Meaning
--edition demo|full the package (default demo)
--version VERSION a specific release instead of the latest
--port N demo: the local port (default 8280)
--server-name NAME HTTPS on the internal network under this DNS name (required for full)
--license-key-file FILE the full package: your licence key (required for full)
--license-server URL another licence server (default https://license.kernoviq.org)
--home DIR installation directory
--upgrade upgrade an existing installation (backup first, rollback when the new release does not start); it keeps the build: the full edition is fetched with the licence key the installation has activated (kernoviqctl upgrade --from-license-server VERSION)
--uninstall [--purge] remove the containers; --purge also deletes every piece of data, the images and the directory
--dry-run check and verify only
--yes never ask

Every other option goes to kernoviqctl install (kernoviqctl install --help). After the installation, kernoviqctl is on the path (/usr/local/bin, or ~/.local/bin for a user installation): kernoviqctl status, stop, start, logs, backup, uninstall.

From the demo to the licensed product

Write to sales@kernoviq.org (Settings → Licence prepares the e-mail with what a quote needs). After payment the licence key arrives by e-mail; paste it into Settings → Licence: the limits are gone at once, and Move to the full edition installs the full build in place — backup first, your data stays (licensing.md, "Moving to the full edition"). For production use, install the full package on a server with the key instead.

Troubleshooting

Symptom Cause and fix
rootless Podman needs its API socket systemctl --user enable --now podman.socket
something already listens on 127.0.0.1:8280 another service has the port: --port 8380
something already listens on port 443 (or 80) another web server on the machine: --https-port 8443 --http-port 8080, or --local
the browser warns about the certificate it does not trust the installation's internal CA yet: import kernoviq-ca.crt from the installation directory (or your organization's certificate: kernoviqctl cert install)
other devices cannot connect a firewall filters TCP 443/80, or the installation was made with --local (kernoviqctl status shows the addresses)
the name 'kernoviq' is already in use on this machine another installation or a development stack holds the name, and sharing it would share its data: KQ_PROJECT=kernoviq2, set for this command and for every later kernoviqctl run
could not pull … the machine cannot reach the image registry (proxy: configure it for Docker or Podman, not only for curl) or the disk is full
the licence server did not hand out the full edition: … the reason follows: a key it does not know (a key issued by hand must be recorded there first), a revoked or ended licence, a release outside the licence's period of updates, or too many downloads today
the release signature does not verify the download was changed on the way, or the script and the release do not belong together: download install.sh again from kernoviq.org
the setup link says the token is invalid the first administrator already exists: sign in on /login

This page is generated from the installation guide that ships with the product.