Skip to content
GitHub
PortDock

Installation guide

PortDock runs on any Linux server you control — a VPS, a machine in your data center or a VM on-premises.

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

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.

Shell
$ 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 domain

If 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.

Shell
$ 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:latest

Keep 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.

Then

  1. 01

    Create the owner account

    Open the dashboard; the first account becomes the owner of the organization.

  2. 02

    Start the proxy

    Servers → localhost → Run setup installs the network and the Traefik proxy.

  3. 03

    Connect your code

    Settings → Git sources: connect GitHub or Azure DevOps, or use any Git URL.

  4. 04

    Deploy

    New resource → Git repository, Docker image, Compose, database or service.

Adding remote servers

  1. 1.Servers → Connect server, and generate an SSH key.
  2. 2.Add the public key to ~/.ssh/authorized_keys on the server (the root user is recommended).
  3. 3.Press Run setup: it installs Docker, the portdock network and the Traefik proxy.
  4. 4.Optional: set a wildcard domain (*.apps.example.com → server IP) for automatic domains and previews.

Configuration

Environment variables of the PortDock container.

VariableDefaultDescription
PORTDOCK_ADDR:8000HTTP listen address
PORTDOCK_PORT8000Host port used by install.sh and docker-compose.yml
PORTDOCK_DATA_DIR/data/portdockDatabase, encryption key, builds and backups
PORTDOCK_PUBLIC_URLhttp://localhost:8000External URL, used for webhooks; https:// enables secure cookies
PORTDOCK_SECRET_KEYgeneratedAES key for secrets — back it up
PORTDOCK_MAX_BUILDS4Parallel deployments
PORTDOCK_NETWORKportdockDocker network shared with Traefik
PORTDOCK_OPENROUTER_URLhttps://openrouter.ai/api/v1API used by the AI assistant

Updates

PortDock checks for a new release whenever it is opened and shows Update available in the sidebar. One click 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.

Recovery from the command line

Locked out? Reset a password or turn off two-factor authentication from the server.

Shell
$ docker exec portdock portdock -reset-password admin@example.com$ docker exec portdock portdock -disable-2fa user@example.com

Development

Go backend and React frontend; contributions are welcome.

Shell
$ 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