Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AZhur771/pivpn-web/llms.txt

Use this file to discover all available pages before exploring further.

PiVPN Web ships as a single Docker image, so getting from zero to a running dashboard takes only a handful of commands. Follow the steps below to install Docker, set up PiVPN with WireGuard, and launch the container.
1

Install Docker

If Docker is not already installed on the machine that will run PiVPN Web, use the official convenience script to install it, then add your user to the docker group so you can run container commands without sudo.
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to the docker group
sudo usermod -aG docker <user>
Log out and back in (or run newgrp docker) for the group change to take effect. Verify the installation with docker --version.
2

Install PiVPN (WireGuard)

On the host machine you want PiVPN Web to manage, run the PiVPN installer and choose WireGuard when prompted for the VPN protocol.
curl -L https://install.pivpn.io | bash
The interactive installer will walk you through selecting your network interface, port, DNS provider, and VPN protocol. See https://pivpn.io for full installation instructions and troubleshooting guidance.
PiVPN Web does not support OpenVPN. When the PiVPN installer asks which VPN protocol to use, select WireGuard.
3

Run PiVPN Web

Start the PiVPN Web container with docker run, passing your SSH credentials and desired admin account details as environment variables.
docker run -d \
  -p 3001:3001 \
  --name pivpn-web \
  --restart=unless-stopped \
  -e SSH_HOST=<pivpn-host-ip> \
  -e SSH_PORT=22 \
  -e SSH_USER=<ssh-user> \
  -e SSH_PASSWORD=<ssh-password> \
  -e ADMIN_USER=admin \
  -e ADMIN_PASSWORD=<secure-password> \
  andrew771/pivpn-web
What each variable does:
VariableDescription
SSH_HOSTIP address or hostname of the machine running PiVPN WireGuard.
SSH_PORTSSH port on the target host. Defaults to 22 if omitted.
SSH_USERLinux username the container will use to authenticate over SSH.
SSH_PASSWORDPassword for the SSH user above.
ADMIN_USERUsername you will log into the PiVPN Web dashboard with.
ADMIN_PASSWORDPassword for the dashboard admin account.
If PiVPN is running on the same machine as the Docker container, use SSH_HOST=host.docker.internal (Docker Desktop on macOS/Windows) or the host’s LAN IP address (e.g. 192.168.1.x) on Linux. Using localhost or 127.0.0.1 will resolve to the container itself, not the host.
The --restart=unless-stopped flag ensures the container starts automatically after a reboot. Remove it if you prefer to start PiVPN Web manually.
4

Open the dashboard

Navigate to http://<host>:3001 in your browser, where <host> is the IP or hostname of the machine running the Docker container.Log in using the ADMIN_USER and ADMIN_PASSWORD values you set in the previous step. You will land on the client list, where you can immediately start creating and managing WireGuard peers.
The admin account is created by a TypeORM migration that runs once on first startup. If the container starts successfully but you cannot log in, check the container logs with docker logs pivpn-web for any migration or SSH connection errors.

​
Next steps

Configuration

Explore all supported environment variables, user roles, TLS setup, and session secret behaviour.

Docker Compose

Use a docker-compose.yml file to manage PiVPN Web alongside other services with a single command.

Remote SSH

Connect PiVPN Web to a PiVPN host on a different machine or network over SSH.

User management

Add viewer and tech accounts, understand role permissions, and manage dashboard access.

Build docs developers (and LLMs) love

Get started for freeTalk to us