0.79.1
Guides

First run

The first sign-in on a fresh install lands in a setup wizard rather than the dashboard. Five steps: unlock the node, name the cluster and its admin account, give it a ZFS pool, define at least one network zone, done. It takes a couple of minutes.

Every screenshot below is a real capture of the wizard on a freshly installed Debian 13 node. Addresses and MAC addresses in them are fictional; nothing else has been touched.

Written against proxdock 0.68.2, whose wizard is five steps. Earlier versions combined the cluster and storage steps and checked the pool only at the very end.

The wizard keeps its state in memory. Reloading the page drops you back to step 1 and the password you used is already spent. If that happens, mint another with proxdock recovery-password and start again. Nothing is written until the last step.

What the installer left you

Installing the package starts the service and prints a banner. That banner is the only place the initial password appears:

──────────────────────────────────────────────────────────────
 proxdock installed and running.

   Web UI:            https://10.42.0.11:8443
   Initial password:  YSun-HmuH-rfee-2KbN

 Log in with an EMPTY username to complete setup. The password
 is single-use and is invalidated when setup completes.
 If locked out later:  proxdock recovery-password
──────────────────────────────────────────────────────────────

The node serves a self-signed certificate until it has a cluster CA, so your browser will warn you. That is expected on a first run; see certificates.md for making it stop.

Lost the banner, or scrolled past it? Run this as root on the host. It is single-use, good for that node only, and expires after fifteen minutes.

proxdock recovery-password

1. Unlock

Leave the username empty and paste the initial password.

The setup wizard's unlock step: a single password field, with the five wizard steps listed above it.
Step 1 of 5. The username field is genuinely meant to be empty here: this is a node-local password, not an account yet.

2. Cluster

A single node is a valid cluster. Joining is for the second node onwards, and needs a token generated on a node that already exists.

The wizard offering to create a new cluster or join an existing one with a token.
Joining is covered in Running a cluster. Everything below is the create path, but the three pages after this are the same either way.

The cluster name is set once and is not currently changeable. It appears in the UI header and in the window title, so something short is easiest to live with.

The admin account is stored in the cluster store rather than on this node, so the same login works on every node that joins later.

The cluster step: a cluster name field and the admin username, password and repeat fields.
This step is only identity. Storage and networking each get a page of their own.

3. Storage

Applications, their data and local backups all live on one ZFS pool on this node. Pick one that exists, or make one here.

The storage step, warning that no ZFS pool was detected and opening straight into the disk picker.
On a host with no pool yet, the picker is the only way forward.

The node confirms the pool before it lets you continue. Naming one that is not there is refused on this step, with the reason, rather than accepted and discovered later.

The storage step refusing to continue, with an error reading: ZFS dataset "tank" does not exist on this node. Pick a pool from the list, or create one from the blank disks the wizard found.
Nothing is written when this fires. tank is the configuration default, which makes it the easiest wrong answer to give.

Creating a pool from a blank disk

Only disks with no partitions, no filesystem signatures and no partition table are offered. Everything else is listed greyed out with the reason attached, so you can see that a disk was considered and why it was refused.

The disk picker showing the OS disk greyed out and labelled "has 3 partition(s)", and a blank 128 GiB disk selected, with an irreversible-action warning below.
The OS disk is not selectable. Selecting a blank one reveals the pool name, the topology, and a warning naming the exact devices about to be taken over.

Pick the disks, name the pool, choose a topology, then press Create pool. This is a separate action rather than part of Continue: the pool is created right then, before the cluster exists.

Devices are added by their stable /dev/disk/by-id names, never /dev/sdX, so the pool survives the kernel enumerating disks in a different order after a reboot.

The storage step after the pool was created, now showing a dropdown with the pool, its free space and ONLINE health.
Once the pool exists the field becomes a picker and the disk section disappears.

4. Networks

A zone names a physical segment cluster-wide: a LAN, a VLAN. Every node maps each zone to one of its own interfaces, and applications reference the zone, never an interface name. That indirection is what lets an application migrate to a node whose NICs are named differently.

The networks step: zone name, a local interface dropdown, subnet, gateway, VLAN tag and an address pool range.
Create cluster stays disabled until every zone is well-formed and has an interface assigned, so a cluster cannot be created with a zone no node can place an address on.

Each application gets a real address from the pool range you set here, with a MAC derived from that address.

The pool range must not overlap anything your DHCP server hands out. ProxDock allocates from it directly and does not ask DHCP first.

The networks step filled in, with the zone mapped to an interface and a warning that no link was detected on it.
The wizard checks carrier on the interface you pick. ⚠ no link detected is a warning rather than a refusal. It will let you map a zone to an unplugged NIC, and applications on that zone will have nowhere to go.

5. Done

The final wizard step confirming the cluster was created.
The initial password is invalidated at this point. From here on you sign in with the admin account.

Signing in

The sign-in screen, with a username field whose placeholder reads "leave empty for recovery / initial password".
The same screen takes either an account or, with the username left empty, a recovery password.

What you land on

The Overview is the whole cluster on one page: inventory counters across the top, aggregate CPU, memory, storage and throughput below them, then live charts and a per-node strip. On a fresh single-node cluster there is not much to see yet, which is itself a useful picture of what "healthy and empty" looks like.

The Overview screen on a fresh single-node cluster, showing 1/1 nodes ready, no containers, and near-zero resource usage.
Vitals are kept in memory on each node and refresh every 10 seconds, so a service restart clears the graphs.

Nodes shows the cluster's members, which one holds the Raft leadership, and each node's replica state. The components table is a drift check: it lists the versions of everything ProxDock drives so a node running an odd ZFS or Docker is visible rather than surprising.

The Nodes screen showing a single node marked leader and deployable, with heartbeat, certificate and pool tiles and a components version table.
Drift is informational. Nodes may legitimately upgrade at different paces.

Settings → Networking lists the zones you defined, cluster-wide.

The networking settings screen listing one zone with its subnet, gateway, VLAN and address pool.
Zones are cluster-wide; the interface each node maps them to is per node, under Nodes → Network.

Settings → Storage shows the pools this node offers and the cluster-wide storage locations.

The storage settings screen showing the pool created during setup.
A pool that is not listed here is left entirely alone by ProxDock.

Where to go next

Nothing is deployed yet. Containers is where applications are created, either from a bundled template or from a Compose file of your own.

The containers screen with no applications yet, offering to create one.
The list is empty on a fresh cluster; the New application button opens the template gallery.

Backups is empty for the same reason. A backup job is defined per application, so there is nothing to schedule until something is deployed.

The backups screen on a fresh cluster, with no backups and no scheduled jobs.
Worth visiting once you have deployed something: a default daily job covering every application is one of the first things to set.