GETTING STARTED

Installing DockBoard

Put DockBoard on your own server with a single command, then reach the dashboard and activate your license.

One command on a fresh server. The installer asks nothing interactively — everything comes from environment variables or sensible defaults, which is what makes it usable from a provisioning script.

Before you start

A fresh Ubuntu 22.04+ or Debian 12+ server with root access.
At least 2 GB of RAM and 20 GB of disk.
A public IPv4 address, with ports 80 and 443 reachable from the internet — Let’s Encrypt validates over HTTP on port 80.
Ports 3000 and 4000 reachable from *your* machine, for the first login before a domain is set up.
Optional but recommended: a domain whose A record you can edit.

You do not need Docker, Node, PostgreSQL, Redis or Caddy installed beforehand. The installer puts all of it in place.

The command

BASH

curl -fsSL https://get.dockboard.io/install.sh | sudo sh

No GitHub access is involved and no source code is downloaded — the script pulls pre-built images from Docker Hub. It then:

01Detects your OS and installs curl, openssl, Docker and the docker compose plugin if they are missing.
02Writes the Compose file to /opt/dockboard with pinned image references.
03Detects the public IP of the machine.
04Generates /opt/dockboard/.env (mode 0600) with cryptographically random values for the database password, the two JWT secrets and the encryption key.
05Seeds the bind-mount targets so Docker does not create them as empty directories.
06Pulls the images, brings the stack up, and waits up to 180 seconds for the API to answer.

Re-running the installer is safe. It preserves .env and the database volume, and only rebuilds the dashboard when the public API URL has changed — that value is baked into the dashboard at build time, so a stale image would call the wrong origin.

Overrides

Variable	Default	Purpose
`DOCKBOARD_DIR`	`/opt/dockboard`	Install root.
`DOCKBOARD_TAG`	`latest`	Image tag to pull.
`PUBLIC_API_URL`	autodetected	Forces the public API URL baked into the dashboard build.
`PUBLIC_DASHBOARD_URL`	same host, port 3000	Dashboard origin used in the links inside outgoing emails.
`DOCKBOARD_RESET=1`	off	Destructive. Wipes `.env` and every Docker volume, then reinstalls from scratch.

First login

Open http://<server-ip>:3000 and register. The first account to register becomes the SUPERADMIN — so do it now, from your own machine, before the address is public.

An onboarding wizard then walks through SMTP, the public domain and whether further signups are allowed. Registration can be closed at any time from Admin → Settings.

Configure SMTP early, from Admin → System Config. Without it, password resets and alert emails silently become no-ops — the panel still works, but it can no longer reach anyone.

Putting a domain in front

01Point an A record at the server’s public IP and wait for it to propagate.
02In Domains → Add domain, enter the hostname and attach it to the dashboard.
03The certificate is issued on the first request to that hostname. Nothing else to do.
04Then set DASHBOARD_BIND=127.0.0.1 in .env and restart, so port 3000 stops answering directly and every visitor goes through TLS.

That last step is the one people skip. Until port 3000 is closed, the dashboard is reachable over plain HTTP as well as HTTPS — including the login form.

Preseeding a license (hosting providers)

An unattended install can arrive already licensed, so the customer never has to visit Admin → License:

BASH

curl -fsSL https://get.dockboard.io/install.sh \
  | sudo DOCKBOARD_LICENSE_KEY='<signed token>' sh

Pass it as an environment variable, not a flag. A command-line argument is visible in ps to every user on the box, and it lands in the invoking shell’s history.

It is a seed, not an override — the distinction matters when a customer later manages their own license:

Imported only on a boot that finds no key already stored.
A key set in the panel always wins.
Removing the key in the panel stays effective — a restart does not resurrect it.
A token that fails to verify is not stored. The instance runs on the free tier and the log says why, which is the honest state rather than a stored key the panel keeps reporting as refused.

The token and a ready-to-run install command both come back from one provisioning call — see the licensing API.

Staying up to date

The API polls for a newer image every five minutes. When one appears it runs a blue/green swap: start the new containers, wait until they are healthy, move the proxy over, then retire the old ones. There is no window where nothing is answering.

Applying automatically requires DOCKBOARD_AUTO_UPDATE=true. Left off, the dashboard simply shows *update available* at Admin → Updates, where you apply it — and read the log — when it suits you.

The host watchdog

Docker’s healthcheck only *labels* a container unhealthy — it never acts. And restart: unless-stopped only covers a process that actually exits. So an API that is alive but wedged stays down until a human notices. The watchdog closes that gap, from outside Docker:

BASH

sudo sh scripts/watchdog/install.sh

It probes the health endpoint every minute. After three consecutive failures it restarts the API container; if the next round still fails it recreates the whole stack, then holds for a ten-minute cooldown so a genuinely broken install is not restarted in a loop.

It probes liveness, never readiness. Restarting the API cannot fix an unreachable database, and a watchdog that tried would just add churn to an outage.

Where things live afterwards

TEXT

/opt/dockboard/
  .env                          secrets, mode 0600
  .dockboard/
    update.log                  the most recent update run
    apps/<slug-id>/             generated stack, one per application
    databases/<slug>/           database stacks
    mail/                       mail server configuration
    reverse-proxy/Caddyfile     regenerated on every domain change

Do not hand-edit anything under .dockboard/. Those files are regenerated from the database — the Caddyfile on every domain change, the update script on every run — so an edit survives exactly until the next write.

If the install does not come up, troubleshooting covers the failures that actually occur.