All installation methods

Audience: PSP / bank infrastructure engineers installing a Hokeka Edge Node on their own hardware. Scope: every supported installation method, on every supported operating system, with the exact commands, flags, verification steps and failure modes.

The Console (dashboard) and the Control Plane (cloud API) are installed by Hokeka staff and are not client installations. This document covers only the Edge Node — the component that evaluates transactions inside the PSP's own estate.

Companion references (deeper detail on specific topics):

01-client-edge-node.md — full edge install reference (ledger, mTLS, sizing)
06-edge-public-install.md — the Console one-liner, operator details
07-first-run-bootstrap.md — fresh-OS prerequisite bootstrap
../edge-client-install-guide.md — requirements, network, sizing
../../edge-host/deploy/README.md — installer internals

1. What you are installing

One Edge Node contains everything needed to evaluate a payment locally:

Component	Role
`edge-host` (Java 21)	The evaluator: serves `POST /edge/evaluate` on TLS 1.3
`edge-engine` (Rust)	The native rule kernel (falls back to the Java interpreter if absent)
Edge Ledger (PostgreSQL 16)	The site's system of record — every evaluation + its decision record, in one local transaction
Aerospike CE	Velocity buckets (26 h) + the rule bundle only
systemd unit / container stack	Process supervision and restart

Data residency: transaction data never leaves the host. Only sealed decision records (ids and outcome) and aggregate metrics are sent outbound over 443.

Golden rules

The node is fail-closed: until a Hokeka platform admin approves it, POST /edge/evaluate answers HOLD and no rule bundle is served.
There is no plaintext listener. The process refuses to start without its TLS keystore.
If the ledger cannot be written, every evaluation answers HOLD (LEDGER_UNAVAILABLE).
Back up the Edge Ledger and data/ (node identity keys). Lose them and you must enrol a new node with a new edge id (the old id returns 409).

2. Supported operating systems

OS	Minimum version	Container mode	Native mode	Notes
Ubuntu	22.04 LTS	✅	✅	Best-tested path
Debian	12 (Bookworm)	✅	✅
RHEL / Rocky / AlmaLinux	9	✅	✅	PostgreSQL 16 from PGDG
SUSE Linux Enterprise / openSUSE	15 SP5	✅	✅	`zypper`
Arch Linux	rolling	✅	⚠️	Native works; Aerospike is not vendor-packaged
Alpine Linux	3.19	✅	✅ x86_64 only	musl-linked core is downloaded automatically
Windows Server	2019 / 2022	✅	❌	Aerospike has no native Windows build
Windows 10 / 11	21H2	✅	❌	Evaluation only, not production

CPU: x86_64 (amd64) or aarch64 (arm64). musl on ARM is refused (no musl/aarch64 core is published) — use container mode there.

Aerospike on Windows: there is no native Windows Aerospike server. On Windows the database runs inside Docker Desktop/WSL2; the installer handles it. (On Linux, --native installs Aerospike CE on the host.)

3. Choose a method

#	Method	OS	Use when
A	Console one-liner (`install-edge.sh` + install token)	Linux	Default for new clients; one command, no values to transcribe
B	Linux container (`install.sh`)	Linux	You have an enrollment code (classic flow) or need explicit control
C	Linux native (`install.sh --native`)	Linux	Containers are prohibited by policy
D	Air-gapped / mirror	Linux + Windows	No internet egress, or an internal artifact mirror
E	Multi-node Edge Site	Linux + Windows	Several nodes share one ledger + one Aerospike cluster
F	Windows Server (`install.ps1`)	Windows	Windows estate (container only)
G	Fresh-OS bootstrap (`hokeka-install.sh` / `.ps1`)	Linux + Windows	Bare OS: install prerequisites first, then the edge role
H	Prebuilt image (`--edge-image`)	Linux + Windows	You build/host your own edge image

Decision path:

New Linux host, Console access ................ Method A (or G then A)
Linux host, enrollment code in hand .......... Method B
Linux, containers forbidden .................. Method C
No outbound internet ......................... Method D
More than one node per site .................. Method E (plus A/B/C/F for the first node)
Windows ...................................... Method F (or G then F)
Bare OS, want a prerequisite audit first ..... Method G
Own image / air-gapped image registry ........ Method H

4. Before you install (all methods)

4.1 Values from the Hokeka Console

Open Console → Edge Nodes (the first-login onboarding modal also walks through this):

Value	Example	Notes
PSP id	`42`	Numeric id, never the PSP code (a code such as `acme` is refused)
Edge id	`acme-eu-1`	The node's stable machine identity
Enrollment code	`ABCD-1234`	Single-use, time-limited (classic flow)
Install token	opaque string	Single-use; default 2 h, max 24 h (one-liner flow)
Control Plane edge URL	`https://edge.hokeka.com`	mTLS endpoint for bundles/metrics

Copy the command the wizard generates rather than composing flags by hand.

4.2 Host sizing

Ledger disk is the dominant cost. Size for at least 5 years; --peak-tps N prints the estimate:

evaluations = N × 86 400 × 365 × 5
disk (GiB)  = evaluations × 2 048 bytes ÷ 2^30 × 1.3    (30 % headroom)

Peak TPS	Evaluations in 5 years	Ledger disk (approx.)
1	157 M	390 GiB
5	788 M	1 953 GiB
10	1 576 M	3 909 GiB
50	7 884 M	19 548 GiB
100	15 768 M	39 097 GiB

Upper bound (peak TPS all day); 2 048 B/evaluation is an estimate — measure in a pilot. Longer retention scales linearly. A full disk means the node answers HOLD.

Host starting points (validate in a pilot):

Tier	Sustained TPS	RAM	vCPU
Evaluation	< 5	8 GB	2
Small	10	16 GB	4
Medium	50	32 GB	8
Large	100+	64 GB	16

install.ps1 has no -PeakTps option — use the formula on Windows.

4.3 Network

Direction	Port	To	When
Outbound	TCP 443	`edge.hokeka.com` (Control Plane edge vhost, mTLS)	Ongoing
Outbound	TCP 443	`packages.hokeka.com` (or GitHub Releases for the one-liner)	Install / upgrade only
Outbound	TCP 443	Docker Hub (`registry-1.docker.io`)	Container mode, image pulls
Inbound	8443/tcp	Your own PSP API nodes only	Ongoing — bound to `127.0.0.1` by default

No inbound port from the internet. Never expose Aerospike (3000) or PostgreSQL (5432).

Proxies: export HTTPS_PROXY / HTTP_PROXY before running; TLS interception is not supported on the Control Plane path.

4.4 Access and prerequisites

Root (Linux) or Administrator (Windows).
Linux: curl, gnupg 2.2+ (release signature checks are fail-closed), systemd; container mode needs Docker 24+/Podman 4+ with Compose 2.20+ (installed automatically if absent).
Windows: Docker Desktop (installed via winget if absent — needs WSL2 and a reboot).

5. Method A — Console one-liner (Linux, install token)

Best for: every new Linux install.

5.1 Mint the token

Console → Edge Nodes → Generate install token → optional display-name hint → copy the one-liner (token included). If it leaks, Revoke it before redemption.

5.2 Run it

curl -fsSL https://hokeka.com/install-edge.sh | sudo bash -s -- --enrol-token 'PASTE_TOKEN_HERE'

Equivalent source (same script, published from the public releases repo):

curl -fsSL https://raw.githubusercontent.com/kevshake/hokeka-edge/main/install-edge.sh \
  | sudo bash -s -- --enrol-token 'PASTE_TOKEN_HERE'

Default Control Plane is https://aml.hokeka.com; override with --control-plane <url>.

5.3 Options (`install-edge.sh`)

Flag	Meaning
`--enrol-token <token>`	Required for a first install (not for `--upgrade`/`--uninstall`)
`--control-plane <url>`	Control Plane base URL (default `https://aml.hokeka.com`)
`--version <semver>`	Pin a release (default: latest)
`--edgeid <id>`	Preferred edge id
`--display-name <name>`	Display-name hint sent with the redeem
`--native` / `--container`	Force the mode (default: container when Docker is present)
`--upgrade`	Re-download and reinstall the same or newer version
`--uninstall`	Stop services and remove `/opt/hokeka` (ledger data kept)
`--purge`	With `--uninstall`: also remove data volumes
`--install-dir <path>`	Install root (default `/opt/hokeka`)
`--skip-preflight`	Skip outbound HTTPS / RAM / disk checks (not recommended)
`--insecure-skip-signature`	Skip detached-signature verification (trusted internal mirrors only)
`-h`, `--help`	Usage

Environment: HOKEKA_RELEASES_REPO (default kevshake/hokeka-edge), HOKEKA_CONTROL_PLANE, HOKEKA_INSTALL_DIR, HTTPS_PROXY / HTTP_PROXY.

5.4 What it does

Detects distro / CPU / libc and installs host dependencies
Preflight: outbound HTTPS to the Control Plane and the release host, RAM and disk, SELinux note on Rocky
Downloads the pinned (or latest) release from kevshake/hokeka-edge
Verifies SHA256SUMS (and the detached signature when published)
Redeems the token → the node is created approved and receives an enrollment code
Installs under /opt/hokeka, registers systemd, starts the stack
Enrols (CSR → Hokeka Edge CA issues the mTLS client certificate) and pulls the first bundle

5.5 Verify

sudo systemctl status hokeka-edge
curl -fk https://localhost:8443/edge/status   # expects "authorization":"authorized", evaluator

Console → Edge Nodes: the node moves to Active (the onboarding modal flips to Node online).

6. Method B — Linux container mode (`install.sh`)

Best for: classic enrollment-code flow, or explicit control over every parameter.

6.1 Download and review

curl -fsSL https://packages.hokeka.com/edge/install.sh -o install.sh
less install.sh                 # read before running as root

6.2 Install

sudo bash install.sh \
  --pspid 42 \
  --edgeid acme-eu-1 \
  --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234 \
  --bind 10.0.0.5 \
  --allow-subnet 10.0.0.0/24 \
  --peak-tps 20

You can also redeem a token instead of a code: replace --enrollment-code with --enrol-token <token>.

6.3 What it provisions

Docker (or Podman) if no runtime is present; Compose stack from edge-host/deploy/docker-compose.yml
Aerospike and the ledger on a private bridge network with no published port
The Edge API published on 127.0.0.1:8443 (widened only by --bind / --allow-subnet)
A generated self-signed TLS keystore, secrets/edge-tls.p12 + password in .env (never overwritten)
A random ledger password in secrets/edge-ledger.pass and .env
A probe of registry-1.docker.io before compose up, so an egress block fails with a named error
A systemd service, then first-boot enrolment

6.4 Operations

cd /opt/hokeka
docker compose ps
docker compose logs -f edge
docker compose down                 # keeps volumes, including the ledger
sudo systemctl restart hokeka-edge

7. Method C — Linux native mode (`install.sh --native`)

Best for: estates that prohibit containers. Linux only — the script warns that native mode is Linux-only (use install.ps1 or containers on Windows/macOS).

sudo bash install.sh --native \
  --pspid 42 --edgeid acme-eu-1 \
  --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234

What is different from container mode:

Concern	Native behaviour
Java	Installs Temurin JRE 21 (Adoptium repo; Alpine uses its own OpenJDK 21)
Aerospike	Installs Aerospike CE on the host, bound to `127.0.0.1`; port 3000 is firewalled (ufw / firewalld / iptables)
Ledger	Installs PostgreSQL 16 (distro package, or PGDG), bound to `127.0.0.1`, port 5432 firewalled
Service	`hokeka-edge.service` (systemd)
Native core	`libedge_engine-linux-<arch>[-musl].so` staged into the library path; absent core falls back to the Java interpreter

7.1 Aerospike is fail-closed and verified

A native install never silently continues without a database. Aerospike is installed only from an integrity-checked archive, in this order:

Release manifest (default, no action needed): the installer fetches aerospike-artifacts.json from the release, verifies the manifest itself against the GPG-signed SHA256SUMS, selects the entry for your distro/arch, downloads the official Aerospike CE tarball and verifies it against the manifest checksum.
Explicit package: --aerospike-package /path/aerospike-ce.tgz — verified against the release SHA256SUMS when it lists the file, otherwise against AERO_PACKAGE_SHA256.
Explicit URL: AERO_PACKAGE_URL=https://… AERO_PACKAGE_SHA256=<sha256> — the checksum is mandatory.

If none is available or verification fails, the install dies with an actionable message (it does not leave you with an Edge and no database). The release pipeline computes those checksums at release time from Aerospike's official tarballs; Hokeka publishes the checksums, not the binaries.

7.2 Distro coverage

apt / dnf / yum / zypper / apk are supported. For a package manager with no PostgreSQL 16 path the installer dies with instructions (never a partial install); passing --ledger-url to a site database avoids the local install entirely.

8. Method D — Air-gapped and mirrored installs

8.1 Internal artifact mirror

sudo bash install.sh --repo-url https://artifacts.internal.example/hokeka-edge \
  --version 1.2.3 \
  --pspid 42 --edgeid acme-eu-1 \
  --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234

The mirror must reproduce the release layout:

<repo>/<channel>.json          -> {"version":"1.2.3"}
<repo>/<version>/SHA256SUMS
<repo>/<version>/SHA256SUMS.asc
<repo>/<version>/edge-host.jar
<repo>/<version>/libedge_engine-linux-<arch>[-musl].so
<repo>/<version>/edge_engine-windows-x86_64.dll
<repo>/<version>/aerospike-artifacts.json

HOKEKA_REPO_URL sets the same value by environment. --channel beta tracks pre-releases.

8.2 Fully offline (artifacts beside the script)

# place edge-host.jar (+ libedge_engine*.so) beside install.sh, then:
sudo bash install.sh --offline \
  --pspid 42 --edgeid acme-eu-1 \
  --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234

For a native offline install also supply the Aerospike package (--aerospike-package).

8.3 Signature policy in an air-gapped estate

Signature verification is fail-closed: an unset pin, missing gpg, missing SHA256SUMS.asc or a bad signature all abort the install. Options:

Mirror SHA256SUMS.asc and keep gpg installed (recommended — this is the same trust anchor);
Only for a mirror you already trust by other means: --insecure-skip-signature (documented as unsafe; never against packages.hokeka.com).

Container mode offline also needs the base image (eclipse-temurin:21-jre, postgres:16-alpine, Aerospike) available in your registry. Export HOKEKA_DOCKER_REGISTRY_MIRROR / DOCKER_REGISTRY_MIRROR, or pre-load docker save tarballs via HOKEKA_DOCKER_IMAGE_TARBALLS_DIR (used by the first-run bootstrap).

9. Method E — Multi-node Edge Site (shared ledger)

Several nodes of one PSP can share one ledger and one Aerospike cluster — that group is an Edge Site. All nodes must use the same --site-id.

Linux

export HOKEKA_LEDGER_PASSWORD='…'          # never on the command line
sudo bash install.sh --native \
  --pspid 42 --edgeid acme-eu-2 \
  --controlplane https://edge.hokeka.com --enrollment-code ABCD-1234 \
  --site-id acme-eu \
  --ledger-url jdbc:postgresql://site-db.internal:5432/hokeka_ledger \
  --ledger-user hokeka_edge

Windows

$env:HOKEKA_LEDGER_PASSWORD = '…'
.\install.ps1 -PspId 42 -EdgeId acme-eu-2 -ControlPlane https://edge.hokeka.com `
  -EnrollmentCode ABCD-1234 -SiteId acme-eu `
  -LedgerUrl jdbc:postgresql://site-db.internal:5432/hokeka_ledger -LedgerUser hokeka_edge

With a shared ledger the installer does not start a local ledger service. Without --site-id the node is a single-node site whose site id is its edge id. Velocity is site-scoped: nodes of the same site share counters; across sites they do not unless you replicate Aerospike with XDR.

10. Method F — Windows Server (`install.ps1`)

Container only (Aerospike has no native Windows build).

10.1 Run in an elevated PowerShell

.\install.ps1 -PspId 42 -EdgeId acme-eu-1 `
  -ControlPlane https://edge.hokeka.com -EnrollmentCode ABCD-1234

Or redeem a Console token (same flow as the Linux one-liner):

.\install.ps1 -EnrolToken 'PASTE_TOKEN_HERE' -ControlPlane https://aml.hokeka.com

10.2 Parameters

Parameter	Meaning
`-PspId <int>`	Required unless `-EnrolToken`: numeric PSP id
`-EdgeId <id>`	Edge id (default `acme-1`)
`-ControlPlane <url>`	Control Plane URL (default `https://edge.hokeka.com`)
`-EnrollmentCode <code>`	Classic single-use enrollment code
`-EnrolToken <token>`	Redeem a Console install token instead
`-Bind <ip>`	API bind address (default `127.0.0.1`)
`-AllowSubnet <cidr>`	Firewall rule for the API port
`-TlsClientAuth none\|want\|need`	Require PSP client certificates
`-TlsTruststore <p12>`	CA that issued your PSP API nodes' certificates (password via `HOKEKA_TLS_TRUSTSTORE_PASSWORD`)
`-LedgerUrl <jdbc>` / `-LedgerUser <role>` / `-SiteId <id>`	Shared site ledger
`-EdgeImage <image>`	Use a prebuilt image instead of building locally
`-Version <semver>` / `-Channel stable\|beta` / `-RepoUrl <url>`	Verified release download
`-InsecureSkipSignature`	Skip signature verification (internal mirrors only)

10.3 Docker Desktop and the reboot

If Docker is absent the script installs Docker Desktop via winget. That needs WSL2 and a sign-in/reboot. To avoid a manual restart, the installer registers a HKCU RunOnce entry that relaunches the same installer, elevated, with the same arguments after the next logon (one UAC prompt). If you prefer to drive it yourself, start Docker Desktop, wait until it reports running, and re-run the command.

10.4 Verified release download (no file copying)

When no edge-host.jar sits beside the script, install.ps1 fetches the signed release exactly like Linux: <channel>.json → <version>/SHA256SUMS → edge-host.jar (+ optional edge_engine.dll). Every downloaded file is SHA-256 verified; a file that is not listed, or whose digest differs, is deleted and the install stops. Fetched artifacts land in .\release\.

Offline Windows: place edge-host.jar (and edge_engine.dll) beside the script — the offline path is used as-is.

10.5 Windows specifics

Files live under the install directory (config, secrets, data); the installer restricts config\ and secrets\ ACLs to SYSTEM + Administrators (the installer is the authority for the exact ACLs on your build).

TLS: a self-signed PKCS#12 is generated. For production, replace it with your CA-issued keystore keeping the same path and alias edge:

keytool -importkeystore -srckeystore your-ca-issued.p12 -srcstoretype PKCS12 `
        -destkeystore secrets\edge-tls.p12 -deststoretype PKCS12 -alias edge
# then update EDGE_TLS_KEYSTORE_PASSWORD in .env and restart the stack

No --self-test option exists on Windows; verify with /edge/status and a single evaluate call (section 13).
Native-core DLL: edge_engine.dll is optional — without it the engine runs on the Java interpreter fallback (functionally equivalent, slower). GET /edge/status reports which one is serving.

11. Method G — Fresh-OS bootstrap (prerequisites first)

Use on a bare Windows or Linux host when you want an audit, or to install prerequisites before the edge role.

Linux

sudo ./scripts/install/hokeka-install.sh --role edge --check          # audit only, exit 1 if missing
sudo ./scripts/install/hokeka-install.sh --role edge --dry-run        # show planned actions
sudo ./scripts/install/hokeka-install.sh --role edge --yes -- \
  --pspid 42 --edgeid acme-eu-1 --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234

Flags: --role control-plane|edge|console, --check, --dry-run, --yes, --install-dir <path>, --build-rust (edge only: build edge-engine from source), and everything after -- is passed to install.sh.

Environment: HOKEKA_DOCKER_REGISTRY_MIRROR / DOCKER_REGISTRY_MIRROR, HOKEKA_DOCKER_IMAGE_TARBALLS_DIR, HTTP_PROXY / HTTPS_PROXY.

Windows (Administrator PowerShell)

.\scripts\install\hokeka-install.ps1 -Role edge -Check
.\scripts\install\hokeka-install.ps1 -Role edge -PspId 42 -EdgeId acme-1 `
  -ControlPlane https://edge.hokeka.com -EnrollmentCode ABCD-1234

Parameters: -Role edge|console|control-plane, -Check, -DryRun, -Yes, -BuildRust, -InstallDir, -PspId, -EdgeId, -ControlPlane, -EnrollmentCode.

12. Method H — Prebuilt image

If you build and host the edge image yourself:

sudo bash install.sh --edge-image registry.internal/hokeka/edge-host:1.2.3 \
  --pspid 42 --edgeid acme-eu-1 --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234

.\install.ps1 -EdgeImage registry.internal/hokeka/edge-host:1.2.3 `
  -PspId 42 -EdgeId acme-eu-1 -ControlPlane https://edge.hokeka.com -EnrollmentCode ABCD-1234

With --edge-image the installers skip artifact download and local image build. Without it they build hokeka/edge-host:local from the release jar.

13. Production TLS and mutual TLS

13.1 Replace the self-signed certificate (required for production)

Linux — at install time (preferred):

sudo bash install.sh \
  --tls-p12 /path/your-ca-issued.p12 \
  --tls-p12-password '…'   # or export HOKEKA_TLS_KEYSTORE_PASSWORD
  --pspid 42 --edgeid acme-eu-1 --controlplane https://edge.hokeka.com --enrollment-code ABCD-1234

The installer copies it to secrets/edge-tls.p12 (mode 600), writes the password file, checks the keystore is readable with keytool, and refuses to continue when the password is missing.

Linux/Windows — after install: keytool -importkeystore into secrets/edge-tls.p12 with alias edge, update EDGE_TLS_KEYSTORE_PASSWORD in .env, restart.

13.2 Mutual TLS from your API nodes

sudo bash install.sh --tls-client-auth need \
  --tls-truststore /path/psp-client-ca.p12 \
  --pspid 42 --edgeid acme-eu-1 --controlplane https://edge.hokeka.com --enrollment-code ABCD-1234
# password via HOKEKA_TLS_TRUSTSTORE_PASSWORD (never on the command line)

.\install.ps1 -TlsClientAuth need -TlsTruststore C:\path\psp-client-ca.p12 `
  -PspId 42 -EdgeId acme-eu-1 -ControlPlane https://edge.hokeka.com -EnrollmentCode ABCD-1234

none (default) serves TLS without client certificates; want requests one; need requires one.

14. Verification checklist (every method)

#	Check	Command / location	Expected
1	Service up	`systemctl status hokeka-edge` (Linux) / `docker compose ps`	Running
2	Authorisation	`curl -fk https://localhost:8443/edge/status`	`"authorization":"authorized"`
3	Evaluator	same payload	`"evaluator":"native"` (or `fallback-java-interpreter`)
4	Ledger	`/edge/status`	ledger state healthy, outbox draining
5	One evaluation	`POST /edge/evaluate` with a test txn	a decision (`ALLOW`/`HOLD`/…), not `HOLD/LEDGE_UNAVAILABLE`
6	Node approved & keys pinned	Console → Edge Nodes → node detail	Active, X25519/Ed25519 fingerprints shown
7	Bundle	node detail	a bundle version + hash
8	Installer self-test	Linux: `--self-test` (auto-on with `--enrol-token`)	polls status for `active`, then one PAN-free `evaluate`

The one-liner (Method A) performs step 8 automatically when it redeems a token.

15. Upgrades, backups, uninstall

Upgrades

Method	Command
A (`install-edge.sh`)	`curl -fsSL https://hokeka.com/install-edge.sh \| sudo bash -s -- --upgrade` (pin with `--version`)
B/C (`install.sh`)	Re-run the installer with the new `--version` (idempotent; never overwrites the keystore)
D (mirror)	Same as B/C with `--repo-url` + `--version`
F (Windows)	Re-run `.\install.ps1` with `-Version <semver>` (or `-Channel`)
G (bootstrap)	Re-run the role command; it re-invokes the edge installer

Backups (do these first)

Edge Ledger (PostgreSQL 16) — the multi-year system of record.
data/ under the install dir — node identity keys (edge-identity.json, mTLS keystore).

Losing them forces a new node enrolment with a new edge id.

Uninstall

# Public bootstrap (keeps ledger data)
curl -fsSL https://hokeka.com/install-edge.sh | sudo bash -s -- --uninstall
# also purge data volumes
curl -fsSL https://hokeka.com/install-edge.sh | sudo bash -s -- --uninstall --purge

# Linux native
sudo systemctl disable --now hokeka-edge
# remove the unit + install dir; drop the ledger only after a backup

# Linux container (keeps volumes, including the ledger)
cd /opt/hokeka && docker compose down

Windows: stop the stack (docker compose down in the install directory) and remove the directory. Revoke the node in the Console so its identity cannot be reused.

16. Troubleshooting

Symptom	Likely cause	Fix
`install token expired` / `revoked`	TTL passed, or an admin revoked it	Mint a new token
403 on activation	`--pspid` mismatch, unknown/used/expired code, or the PSP is not `ACTIVE`	Use the wizard's values; ask Hokeka to activate the PSP
`Cannot reach GitHub Releases` (one-liner)	Firewall/proxy	Allow `github.com` + `objects.githubusercontent.com`, set `HTTPS_PROXY`
`could not fetch SHA256SUMS` / signature failure	Mirror or TLS interception	Fix egress; never bypass the signature against the public host
Checksum mismatch	Truncated download / bad mirror	Re-run; verify the mirror
`cannot reach registry-1.docker.io`	Docker Hub egress blocked	Allow TCP 443 to Docker Hub, or mirror/pre-load images
Native: "Aerospike … unverified/unobtainable"	No verified package	Supply `--aerospike-package` / `AERO_PACKAGE_URL`+`AERO_PACKAGE_SHA256`, or use container mode
Native: PGDG/Postgres message	Distro has no PostgreSQL 16 path	Use `--ledger-url` to a site database, or install PostgreSQL 16 and re-run
Evaluate returns `HOLD`	Node not approved, or ledger unavailable	Approve in the Console; check `/edge/status` ledger fields
`409` on enrolment	Edge id already exists (keys lost/reused)	Enrol a new node with a new edge id
SELinux denials (Rocky)	Enforcing mode	Review the audit log; allow systemd/container contexts per policy
Windows: Docker not running after install	Docker Desktop needs WSL2 + reboot	Sign in; the `RunOnce` entry resumes the install, or re-run manually
`--retention-days` warning	Retention is a Console setting	Set it in Console → Settings → Data Retention

17. Appendix — full flag reference

`install.sh` (Linux)

--native · --repo-url <url> · --channel stable|beta · --version <semver> · --offline · --edge-image <image> · --bind <ip> · --pspid <int> · --edgeid <id> · --controlplane <url> · --data-dir <path> · --allow-subnet <cidr> · --enrollment-code <code> · --enrol-token <token> · --controlplane-signing-key <b64> · --controlplane-ingest-key <b64> · --tls-client-auth none|want|need · --tls-truststore <p12> · --tls-p12 <p12> · --tls-p12-password <pw> · --insecure-skip-signature · --self-test / --no-self-test · --ledger-url <jdbc> · --ledger-user <role> · --site-id <id> · --peak-tps <n> · --data-file-size <16G> · --aerospike-package <tgz> · --retention-days <n> (ignored, warns) · -h/--help

Environment: HOKEKA_REPO_URL, HOKEKA_LEDGER_PASSWORD, HOKEKA_TLS_KEYSTORE_PASSWORD, HOKEKA_TLS_TRUSTSTORE_PASSWORD, AERO_PACKAGE_URL, AERO_PACKAGE_SHA256, HTTP_PROXY/HTTPS_PROXY.

`install.ps1` (Windows)

-PspId · -EdgeId · -ControlPlane · -EnrollmentCode · -EnrolToken · -Bind · -AllowSubnet · -TlsClientAuth · -TlsTruststore · -LedgerUrl · -LedgerUser · -SiteId · -EdgeImage · -Version · -Channel · -RepoUrl · -InsecureSkipSignature

Environment: HOKEKA_LEDGER_PASSWORD, HOKEKA_TLS_TRUSTSTORE_PASSWORD.

`install-edge.sh` (Linux one-liner)

--enrol-token · --control-plane · --version · --edgeid · --display-name · --native / --container · --upgrade · --uninstall · --purge · --install-dir · --skip-preflight · --insecure-skip-signature · -h/--help

Environment: HOKEKA_RELEASES_REPO, HOKEKA_CONTROL_PLANE, HOKEKA_INSTALL_DIR, HTTPS_PROXY/HTTP_PROXY.

Files created by an install

Paths are relative to the install directory (the one-liner uses /opt/hokeka; install.sh uses the directory containing the script; --data-dir relocates data/).

<install-dir>/
  .env                      # runtime configuration (mode 600)
  secrets/edge-tls.p12      # TLS keystore (alias "edge")
  secrets/edge-tls.pass     # keystore password
  secrets/edge-ledger.pass  # generated ledger password (local ledger)
  secrets/psp-client-ca.p12 # only when --tls-truststore was supplied
  data/edge-identity.json   # X25519 + Ed25519 node keys (back these up)
  data/mtls/edge-client.p12 # CA-issued mTLS client certificate (auto-renewed)
  aerospike/aerospike.conf  # native mode
  docker-compose.yml        # container mode

18. Support

Console → Edge Nodes → node detail (status, fingerprints, bundle, recent metrics)
GET /edge/status on the node (authorisation, evaluator, ledger, outbox)
Hokeka support: support@hokeka.com — include the node's edge id, install method, and the failing command/output. Never send secrets, keystore passwords, or transaction data.

1. What you are installing​

2. Supported operating systems​

3. Choose a method​

4. Before you install (all methods)​

4.1 Values from the Hokeka Console​

4.2 Host sizing​

4.3 Network​

4.4 Access and prerequisites​

5. Method A — Console one-liner (Linux, install token)​

5.1 Mint the token​

5.2 Run it​

5.3 Options (install-edge.sh)​

5.4 What it does​

5.5 Verify​

6. Method B — Linux container mode (install.sh)​

6.1 Download and review​

6.2 Install​

6.3 What it provisions​

6.4 Operations​

7. Method C — Linux native mode (install.sh --native)​

7.1 Aerospike is fail-closed and verified​

7.2 Distro coverage​

8. Method D — Air-gapped and mirrored installs​

8.1 Internal artifact mirror​

8.2 Fully offline (artifacts beside the script)​

8.3 Signature policy in an air-gapped estate​

9. Method E — Multi-node Edge Site (shared ledger)​

10. Method F — Windows Server (install.ps1)​

10.1 Run in an elevated PowerShell​

10.2 Parameters​

10.3 Docker Desktop and the reboot​

10.4 Verified release download (no file copying)​

10.5 Windows specifics​

11. Method G — Fresh-OS bootstrap (prerequisites first)​

12. Method H — Prebuilt image​

13. Production TLS and mutual TLS​

13.1 Replace the self-signed certificate (required for production)​

13.2 Mutual TLS from your API nodes​

14. Verification checklist (every method)​

15. Upgrades, backups, uninstall​

Upgrades​

Backups (do these first)​

Uninstall​

16. Troubleshooting​

17. Appendix — full flag reference​

install.sh (Linux)​

install.ps1 (Windows)​

install-edge.sh (Linux one-liner)​

Files created by an install​

18. Support​