Installation guide
PortDock runs on any Linux server you control — a VPS, a machine in your data center or a VM on-premises — and on Kubernetes.
Requirements
- A Linux server — Ubuntu or Debian recommended — with root access
- Ports 80 and 443 free for the HTTPS proxy
- Enough memory for your applications and databases (SQL Server needs about 2 GB)
- Docker — the installer adds it if it is missing
- For Kubernetes in one command: a fresh server and a DNS record (A) of your domain pointing to it
01
Option 1 — installer
Installs Docker if it is missing and starts PortDock. Add a domain that points to the server to get HTTPS for the dashboard.
$ git clone https://github.com/gavrilencu/PortDock.git portdock && cd portdock$ sudo bash install.sh # dashboard on http://<server-ip>:8000$ sudo bash install.sh https://portdock.example.com # or with a domainIf port 8000 is taken, the installer picks the next free port and prints the address (or set PORTDOCK_PORT=9000).
02
Option 2 — Docker image
When Docker is already installed.
$ docker run -d --name portdock --restart unless-stopped \ -p 8000:8000 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /data/portdock:/data/portdock \ -e PORTDOCK_PUBLIC_URL=http://<server-ip>:8000 \ ghcr.io/gavrilencu/portdock:latestKeep the data directory mounted at the same path as on the host (/data/portdock): builds and backups are mounted into helper containers by absolute path.
03
Option 3 — Kubernetes on a fresh server, all in one
Asks for the domain of the dashboard, then installs k3s, cert-manager with Let's Encrypt, Docker for the builds and a private registry, and starts PortDock on https://your-domain with a test and a prod server ready.
$ curl -fsSL https://github.com/gavrilencu/PortDock/releases/latest/download/install-kubernetes.sh | sudo bashIt prints a link with a setup token: open it to create the owner account, so nobody else can claim the dashboard first. Later updates are made from the dashboard; running the installer again repairs the setup and keeps passwords and data.
04
Option 4 — an existing Kubernetes cluster
PortDock runs in the cluster and deploys to it with its own service account.
$ kubectl apply -f https://raw.githubusercontent.com/gavrilencu/PortDock/main/deploy/kubernetes/portdock.yaml$ kubectl -n portdock rollout status statefulset/portdock$ kubectl -n portdock port-forward svc/portdock 8000:8000 # then open http://localhost:8000To deploy to a cluster from a PortDock on a Docker server instead, run connect.sh where kubectl reaches the cluster and paste the kubeconfig it prints in Servers → Connect server → Kubernetes cluster.
Then
- 01
Create the owner account
Open the dashboard; the first account becomes the owner of the organization.
- 02
Start the proxy
Servers → localhost → Run setup installs the network and the Traefik proxy (on Kubernetes, the cluster's ingress controller does it).
- 03
Connect your code
Settings → Git sources: connect GitHub or Azure DevOps, or use any Git URL.
- 04
Deploy
New resource → Git repository, Docker image, Compose, database or service.
Adding remote servers
- 1.Servers → Connect server, and generate an SSH key.
- 2.Add the public key to ~/.ssh/authorized_keys on the server (the root user is recommended).
- 3.Press Run setup: it installs Docker, the portdock network and the Traefik proxy.
- 4.Optional: set a wildcard domain (*.apps.example.com → server IP) for automatic domains and previews.
Configuration
Environment variables of the PortDock container.
| Variable | Default | Description |
|---|---|---|
| PORTDOCK_ADDR | :8000 | HTTP listen address |
| PORTDOCK_PORT | 8000 | Host port used by install.sh and docker-compose.yml |
| PORTDOCK_DATA_DIR | /data/portdock | Database, encryption key, builds and backups |
| PORTDOCK_PUBLIC_URL | http://localhost:8000 | External URL, used for webhooks; https:// enables secure cookies |
| PORTDOCK_SECRET_KEY | generated | AES key for secrets — back it up |
| PORTDOCK_MAX_BUILDS | 4 | Parallel deployments |
| PORTDOCK_NETWORK | portdock | Docker network shared with Traefik |
| PORTDOCK_OPENROUTER_URL | https://openrouter.ai/api/v1 | API used by the AI assistant |
| PORTDOCK_TRUSTED_PROXIES | private ranges | Proxies whose X-Forwarded-For is trusted for client addresses |
| PORTDOCK_SETUP_TOKEN | – | Required to create the owner account; set by the Kubernetes installer |
| PORTDOCK_KUBE_SERVERS | – | In a cluster: the servers created with the owner account (name=namespace pairs) |
Updates
PortDock checks for a new release whenever it is opened and shows Update available in the sidebar. One click checks the signature of the new image, backs up the database and the key, recreates PortDock with the new version and rolls back automatically if it doesn't start. Applications keep running throughout; automatic updates at night can be enabled. In Kubernetes as well: a job of the current version moves PortDock to the new one and restores the previous one if it does not start.
Recovery from the command line
Locked out? Reset a password or turn off two-factor authentication from the server.
$ docker exec portdock portdock -reset-password admin@example.com$ docker exec portdock portdock -disable-2fa user@example.com$ # on Kubernetes$ kubectl -n portdock exec statefulset/portdock -- portdock -reset-password admin@example.comDevelopment
Go backend and React frontend; contributions are welcome.
$ make dev-api # backend on :8000$ make dev-ui # Vite on :5173$ make test # go vet, go test and the TypeScript check$ make build # bin/portdock with the interface embedded