Install

ProxDock installs from a public apt repository, with a one-line script that prepares the host first. The binary is static and embeds its own web UI, so there is nothing to install alongside it beyond the system tools it drives: ZFS, Docker and skopeo.

Status: complete. Built and tested for the three platforms below; arm64 is planned but not built.

Supported platforms#

One package per release, built from the same source, published to one suite per distribution.

amd64 only for now.

Install#

One command. It checks the architecture and the release, puts ZFS and Docker on the host the way that distribution wants them, adds the repository, and installs ProxDock, so apt upgrade keeps it current afterwards.

wget -qO- https://proxdock.whydoesnothing.work/install.sh | sudo sh

wget is listed first deliberately: a minimal Debian 13 install has wget and no curl, while Ubuntu has both. curl -fsSL <url> | sudo sh works equally well where you have it.

The script is POSIX sh rather than bash, so dash runs it on both distributions. Every step is a function with main on the last line, which means a truncated download does nothing at all rather than executing as far as it got. That is the failure mode that actually matters when the ZFS step is halfway through.

Knobs#

All optional, all environment variables. Put them after sudo:

wget -qO- https://proxdock.whydoesnothing.work/install.sh \
  | sudo PROXDOCK_VERSION=0.67.0 sh

Or do it by hand#

Nothing in the installer is magic. Docker should come from Docker's own repository, not the distribution's; the rest is ZFS and two apt commands.

On Debian, ZFS lives in contrib because of the licence, and the module is compiled against your running kernel, which means matching headers, and a reboot if you have upgraded the kernel without one:

apt install zfsutils-linux zfs-dkms zstd skopeo

On Ubuntu the module is prebuilt for each kernel, so there is no compiler and no DKMS wait. But cloud and minimal images often omit the package, and skopeo is in universe:

apt install linux-modules-extra-$(uname -r) zfsutils-linux zstd skopeo

Then the repository. The keyring package's postinst writes the sources file for whichever release you are on, so there is no /etc/apt to hand-edit and no key to place yourself. It is written once and never rewritten.

curl -fsSLO https://packages.whydoesnothing.work/wdnw-archive-keyring.deb
apt install ./wdnw-archive-keyring.deb
apt update && apt install proxdock

After it installs#

Installing starts the service and prints the web UI address and a single-use initial password. Sign in with an empty username and that password; the setup wizard takes it from there, and the initial password is invalidated once setup completes.

First run walks the whole wizard with a screenshot of every step.

If there is no ZFS pool yet, the wizard scans the disks and offers to create one on stable by-id names, refusing anything not provably blank. That is why there is no zpool create above: a line here would be a worse version of it, and would invite running it against a disk the wizard would have declined.

Schema migrations are append-only and ship inside the binary, so upgrade every node in a cluster together when a release adds one. The changelog says which releases do.

Locked out#

Run this as root on the host itself. It is single-use, good for that node only, and expires after fifteen minutes.

proxdock recovery-password

HTTPS#

A node serves a self-signed certificate on first start, replaced by a cluster-CA-issued one once it joins a cluster. Neither is publicly trusted, so a browser will complain until you configure real certificates. See certificates.md.

Where things live#

PROXDOCK_DATA_DIR overrides the state directory, which is useful for running a second instance locally during development.