pre-1.0
Guides

First run

The first sign-in on a fresh install lands in a setup wizard rather than the dashboard. It unlocks the node, creates the cluster, gives it storage, and defines at least one network zone. 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.

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:  GdYW-EQHX-VX6k-Hx8H

 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 four wizard steps listed above it.
Step 1 of 4. The username field is genuinely meant to be empty here: this is a node-local password, not an account yet.

2. Create or join

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's second step, 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.

3. Name the cluster and give it storage

The cluster step: a cluster name field, a storage section warning that no ZFS pool was detected, and the admin account fields.
On a host with no pool yet, the storage section opens straight into the disk picker.

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.

Application storage is where every application's dataset will be created. This field names a pool that already exists — if you have made one yourself, type it here and move on.

If you have not made a pool yet, do not type a name into that field. Naming a pool that does not exist is accepted, and the cluster is created against it. Use the disk picker below instead, which fills the field in for you once the pool is real.

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 two disks: 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 the blank disk reveals the pool name, the topology, and a warning naming the exact devices that are about to be taken over.

Pick the disks, name the pool, choose a topology, then press Create pool. This is a separate action, not 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 section 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.

The admin account

The completed cluster step with the cluster named, a pool selected, and the admin username and password filled in.
This account lives in the cluster store, so the same login works on every node that joins later.

4. Network zones

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.
One zone is enough to finish. More can be added here or later under Settings → Networking.

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, not 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.