Installing ozpanel

Overview

One bare Debian machine becomes one cluster-capable node. Two installers, same sequence: config, bootstrap, first login.

• scripts/install-node.shFrom your machine, a clean source checkout. Builds the release, copies it over SSH, drives the install.
• ozpanel installOn the target, from a release binary already placed there.

No public download yet. Build with scripts/release.sh.

Requirements

• Your machineClean git tree. sshpass ssh scp curl jq, the release toolchain. Reach TCP 22 and 9600 on the target.
• Outbound from targetDebian mirrors, CrowdSec repository, GitHub (web terminal), public DNS on UDP 53, HTTPS (public IP check, ACME).
• Bundled in the binaryCaddy, tinc, Roundcube, Rspamd, Garage, JuiceFS. ozpanel version lists them with sha256.

Ports

Admin ports are open until the first management source is added:

ozpanel admin allow-ip 198.51.100.5 --label office --scope all   # all | console (default)

DNS records

Example: node panel.example.com, address 203.0.113.10, mail domain example.com.

• Name not ready--http-only and log in at http://203.0.113.10:9600, or --dns-from an existing panel.
• Server identity checkGET /mail/identity; POST /mail/identity/publish publishes what the node can.
• Other NS namesinit-config --nameservers, or PUT /dns/platform/nameservers {"nameservers":["ns1.example.com","ns2.example.com"]}. Glue needed only for names inside the zone they serve.
• Per mail domainMX, SPF, DKIM, DMARC, autoconfig, SRV: one call. See Mail · Deliverability.

install-node.sh

scripts/install-node.sh --host 203.0.113.10 --fqdn panel.example.com --admin-email admin@example.com

Secrets not given are asked without echo. Nothing read from the environment.

1. Refuse a dirty tree; build; refuse any ABSENT artifact.
2. --first-login: change the temporary root password.
3. Pre-flight: OS, arch, root, memory, disk, uid map.
4. Copy to /usr/local/lib/ozpanel; ozpanel init-config (existing config kept).
5. --dns-from: publish the A record.
6. ozpanel bootstrap, one line per step. Prints the install screen URL.
7. Prove the panel on 9600 runs the built binary.
8. Create the first login.
9. scripts/verify-node.sh from outside; save the keep directory.

Exit status non-zero if the bootstrap or the outside check failed.

ozpanel install

/usr/local/lib/ozpanel/ozpanel install --fqdn panel.example.com --admin-email admin@example.com

Checks before writing: root · Debian 12/13 · 3800 MB · no config · floating flags valid · FQDN resolves publicly to this machine (or the floating address).

Sequence: init-config → bootstrap (--pause-at-handover with a floating IP) → admin create → floating-IP job → bootstrap again.

CLI used at install

Bootstrap steps

32 steps on a first node: 22 by the command, then migrations, then 10 by the running panel. Idempotent; each prints ASSERT lines.

An install_nftables "no policy applied" warning is expected; the panel applies it at start.

Following and resuming

Completed steps stay done. A failed step stops the job with its ASSERT lines.

Never rerun ozpanel install over an existing config. Use ozpanel bootstrap; the binary prints that too. Panel down: journalctl -u ozpanel -n 50.

Floating IP through a hub

A hub holds the address; tinc carries it to the node. It becomes the node's public identity: A record, mail source, certificates. Own address stays node.real_ip.

scripts/install-node.sh --host 203.0.113.10 --fqdn panel.example.com --admin-email admin@example.com \
  --floating-ip 203.0.113.11 --vps-ip 198.51.100.5
ozpanel install --fqdn panel.example.com --admin-email admin@example.com \
  --floating-ip 203.0.113.11 --hub-ip 198.51.100.5 --hub-password '…'

• Modesautomatic (hub root password, built over SSH) · manual (tinc invitation from the hub).
• WhenBoth installers: at the handover, before panel-side steps, so apply_binds and the node certificate use the floating address.
• JobPOST /cluster/floating-ip: tinc_vps_cleanup · tinc_vps_create · tinc_vps_invite · tinc_join · tinc_configure · tinc_test · tinc_switch (SSH drops) · tinc_verify.
• Checkozpanel install --floating-status, GET /cluster/floating-ip: in_force: true, outbound_ip = floating address.
• Tunnel downDefault route blackholed; no mail from the wrong address. Older nodes' tinc-down scripts rewritten to match.
• Failed jobNot resumable (hub password in memory only). Node keeps its own address; submit again.
• ConsoleCluster → Floating IP form.

First login

• https://panel.example.comPanel under the node name.
• http://203.0.113.10:9600Direct; login over HTTP only with --http-only.
• /admin/installInstall screen, recovery-token login.
• /docsSwagger UI; API base /api/v1.

ozpanel admin create --email admin@example.com          # password generated, printed once
TOK=$(ozpanel admin token --email admin@example.com --name check --ttl 30m)
curl -s -H "Authorization: Bearer $TOK" http://127.0.0.1:9600/api/v1/ozpanel/health

What to keep

install-node.sh copies these to the keep directory (0600). After ozpanel install, copy them yourself.

Checking it worked

Config file

/etc/ozpanel.json, 0640, written by init-config. Restart ozpanel after an edit. Secrets: one file each in secrets_dir.

Also created: /usr/local/bin/ozpanel symlink · /etc/ozpanel/pki/ · ozpanel.service (always restarts, 5 s to 2 min backoff) · ozpanel-recover.timer (enable with systemctl enable --now ozpanel-recover.timer).

Updating

One artifact: binary with migrations, templates, consoles, API reference and the six bundled programs. Deployed to the master only; members take it over a signed channel.

# find the master
curl -s -H "Authorization: Bearer $TOK" http://127.0.0.1:9600/api/v1/cluster/roles \
  | jq -r '.data.nodes[] | select(.authority=="master_holder") | .node'
# token into a 0600 file, then deploy from a clean checkout
ozpanel admin token --email admin@example.com --name deploy --ttl 30m --dangerous > deploy.tok
scripts/deploy-node.sh --host panel.example.com --token-file deploy.tok

1. Master and clean tree checked; one release built.
2. Staged at /usr/local/lib/ozpanel/updates/ozpanel; signed (POST /cluster/updates/sign, CA holder only).
3. Applied: POST /cluster/self-update; unsigned refused. Master proven.
4. Rolled out: POST /cluster/updates/publish, one member at a time; each verifies, swaps, restarts.
5. Migrations last, by the primary, Galera appliers quiesced (POST /cluster/updates/migrate by hand).
6. Measured: GET /cluster/updates/verify; non-zero exit on any difference.

• ConvergencePublish · master's push to returning nodes · ozpanel pull-release before every start (--timeout 60s, --restart-if-pulled, always exits 0).
• SafetySignature checked with the CA cert · staged binary must run version · previous kept as ozpanel.bak (manual rollback) · publish refuses a disagreeing cluster unless ?force=1.
• Hand-copied binaryReplaced on next start. Only the signed channel persists.
• ConsoleCluster → Updates: sign, self-update, publish, rollout.

Reinstalling

• Rerun installerIdempotent. Keeps config and app_key.
• Rebuilt machine--new-host-key; new keep directory per run; reuse the original app_key to read stored credentials.
• init-config --forceNew identity. Never on a serving cluster member.
• UninstallNot available. Reinstall the OS.

Next: The cluster