Skip to content

Backend — Community edition

The Community edition is free and open source. It gives you the full admin panel, client management, OIDC/SSO and TOTP login, per-OS client auto-update, and an audit log. You upload WireGuard® .conf files for your clients by hand — automatic peer provisioning is a Pro feature.

Installing takes about 15 minutes: build one Docker image, write two small files, start the stack.

Prerequisites

  • A Linux server with Docker Engine and the Docker Compose plugin — see Prerequisites.
  • An HTTPS reverse proxy (Nginx Proxy Manager, Caddy, Traefik, …) and a domain name pointed at the server. You can skip this for a quick local test, but sign-in cookies and SSO need real HTTPS in front.
  • git installed on the server.

Steps

1. Get the source

git clone https://github.com/valeniusvpn/valenius.git
cd valenius

2. Build the backend image

docker build -f Backend/Dockerfile -t valenius-backend:latest .

Build from the repo root

Run this from the top of the cloned repository, not from inside Backend/ — the build needs files from Shared/ too. If you see an error mentioning Shared/Valenius.Shared, you're in the wrong directory.

3. Create a deployment folder

Your running stack lives in its own folder, outside the cloned source:

mkdir -p ~/valenius-server/data/downloads
cd ~/valenius-server

4. Create the .env file

Create a file named .env with the following content, replacing every change-me value with a strong random one (generate them with openssl rand -hex 24):

# .env
DB_PASSWORD=change-me-a-strong-random-password

# Bootstrap admin — your first login. Also your emergency fallback later.
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=change-me-a-strong-random-password

# Host port the backend listens on (your reverse proxy forwards to this).
BACKEND_PORT=9001

5. Create the docker-compose.yml file

Create a file named docker-compose.yml next to .env, with exactly this content:

# docker-compose.yml
services:
  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: valenius
      POSTGRES_USER: valenius
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - valenius-database-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U valenius -d valenius"]
      interval: 10s
      timeout: 5s
      retries: 5

  backend:
    image: valenius-backend:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      ASPNETCORE_ENVIRONMENT: Production
      ASPNETCORE_HTTP_PORTS: ""
      ConnectionStrings__DefaultConnection: >-
        Host=db;Port=5432;Database=valenius;Username=valenius;Password=${DB_PASSWORD}
      DataProtection__KeysPath: /app/keys
      Valenius__ManifestPath: /app/data/versions.json
      Valenius__DownloadsPath: /app/data/downloads
      Valenius__AdminEmail: ${ADMIN_EMAIL}
      Valenius__AdminPassword: ${ADMIN_PASSWORD}
    volumes:
      - ./data:/app/data
      - valenius-keystore:/app/keys
    ports:
      - "${BACKEND_PORT}:8080"

volumes:
  valenius-database-data:
  valenius-keystore:

6. Start the stack

docker compose up -d
docker compose logs -f backend

The first start creates the database schema, generates the server's API key, and creates your admin account from .env — all automatically. Wait until the log shows a line beginning with Now listening on:, then press Ctrl+C to leave the logs (the stack keeps running).

7. Put your reverse proxy in front

In your reverse proxy, create an HTTPS host (for example vpn.example.com) that forwards to http://<server-ip>:9001 (or whatever you set as BACKEND_PORT).

Verify it works

  1. Run docker compose ps — both containers show running, and db shows healthy.
  2. Open https://vpn.example.com/ (your proxy hostname) in a browser — the Valenius sign-in page appears.
  3. Sign in with the ADMIN_EMAIL and ADMIN_PASSWORD from your .env — the admin panel opens.
  4. Check Admin → About — it shows the running backend version.

That's a working backend. Continue with First steps after install to create your first customer and connect a client.

Common problems

The build fails mentioning Shared/Valenius.Shared. You ran docker build from inside Backend/. Change to the top of the cloned repository and run it again exactly as shown in step 2.

docker compose up fails with "port is already allocated". Another service is using the port. Pick a different BACKEND_PORT in .env and run docker compose up -d again.

The backend log shows database connection errors at first start. Usually just timing — the backend waits for the database health check, so give it a minute. If it keeps failing, check DB_PASSWORD in .env for stray quotes or spaces.

I changed DB_PASSWORD in .env and now the backend can't connect. The database keeps the password it was first created with — changing .env later only changes what the backend sends. Either change it back, or reset the database volume (docker compose down -v — this deletes all data) and start fresh.

I can sign in, but only when I access the port directly — through the proxy I land back on the sign-in page. Your proxy isn't forwarding HTTPS properly. Make sure the proxy host uses HTTPS with a valid certificate and forwards to the backend port over plain HTTP. Learn more →

I forgot the admin password. Set a new ADMIN_PASSWORD in .env and run docker compose up -d again — the bootstrap admin's password is updated on every container start.

Upgrading later

cd ~/valenius   # your clone from step 1
git pull
docker build -f Backend/Dockerfile -t valenius-backend:latest .
cd ~/valenius-server
docker compose up -d

Database upgrades happen automatically at startup — there is no separate migration step, and your data is kept.