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.

Docker Compose is the recommended way to run PiVPN Web in production. It keeps your configuration in a single versioned file, handles container lifecycle management, and makes it easy to update or reconfigure the service without having to remember long docker run flags.

​
The docker-compose.yml file

The following is the docker-compose.yml shipped with PiVPN Web. It defines a single service that exposes the web UI on port 51821 and restarts automatically unless you explicitly stop it. 
version: "3.3"
services:
  pivpn-web:
    image: andrew771/pivpn-web
    container_name: pivpn-web
    ports:
      - "51821:51821"
    restart: unless-stopped
    environment:
      # Uncomment this to connect to a remote PiVPN host
      - SSH_HOST=192.168.1.2
      # - SSH_PORT=22

​
Field reference

FieldDescription
imageThe published Docker Hub image (andrew771/pivpn-web). Pin to a semver tag (e.g. andrew771/pivpn-web:1.1.2) for stability.
container_nameNames the running container pivpn-web so you can reference it in docker commands without looking up the container ID.
portsMaps host port 51821 to container port 51821. The application listens internally on the port defined by the PORT environment variable (default 3001), but the published image defaults PORT to 51821. Change the left-hand value to expose the UI on a different host port.
restart: unless-stoppedDocker automatically restarts the container on daemon restarts and after crashes. It will not start the container if you stopped it manually with docker compose stop.
environmentPasses environment variables into the container at runtime. All PiVPN Web configuration is done through environment variables.

​
Adding required environment variables

Expand the environment block to include all credentials needed for SSH access and dashboard authentication: 
version: "3.3"
services:
  pivpn-web:
    image: andrew771/pivpn-web
    container_name: pivpn-web
    ports:
      - "51821:51821"
    restart: unless-stopped
    environment:
      - SSH_HOST=192.168.1.2
      - SSH_PORT=22
      - SSH_USER=pi
      - SSH_PASSWORD=raspberry
      - ADMIN_USER=admin
      - ADMIN_PASSWORD=yourpassword
VariableRequiredDescription
SSH_HOSTYesIP address or hostname of the machine running PiVPN.
SSH_PORTNo (default 22)SSH port on the PiVPN host.
SSH_USERYesSSH username used to connect to the PiVPN host.
SSH_PASSWORDYesSSH password for the above user.
ADMIN_USERYesUsername for the PiVPN Web admin account.
ADMIN_PASSWORDYesPassword for the PiVPN Web admin account.

​
Starting the service

1

Create the compose file

Save the docker-compose.yml content above to a directory on your Docker host, for example ~/pivpn-web/docker-compose.yml.
2

Start the service

From the directory containing your docker-compose.yml, run:
docker compose up -d
Docker will pull the image if it is not already present and start the container in the background. The dashboard will be available at http://<your-host>:51821.
3

View logs

Stream live logs from the running container:
docker compose logs -f pivpn-web
Press Ctrl+C to stop following. Omit -f to print existing logs and exit.
4

Stop the service

To stop the container without removing it:
docker compose stop
To stop and remove the container (the image is kept):
docker compose down

​
Using a .env file for secrets management

Instead of embedding credentials directly in docker-compose.yml, you can store them in a .env file in the same directory. Docker Compose automatically loads this file and substitutes the values. .env 
SSH_HOST=192.168.1.2
SSH_PORT=22
SSH_USER=pi
SSH_PASSWORD=raspberry
ADMIN_USER=admin
ADMIN_PASSWORD=yourpassword
docker-compose.yml (referencing the variables) 
version: "3.3"
services:
  pivpn-web:
    image: andrew771/pivpn-web
    container_name: pivpn-web
    ports:
      - "51821:51821"
    restart: unless-stopped
    environment:
      - SSH_HOST=${SSH_HOST}
      - SSH_PORT=${SSH_PORT}
      - SSH_USER=${SSH_USER}
      - SSH_PASSWORD=${SSH_PASSWORD}
      - ADMIN_USER=${ADMIN_USER}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
Add .env to your .gitignore file so that credentials are never committed to version control. You can safely commit docker-compose.yml and share it with your team — the secrets stay local.

Build docs developers (and LLMs) love

Get started for freeTalk to us