Run a server - Bump VPN Operators

Run a community VPN server with Docker

A Bump VPN server is an OpenVPN server plus a small credential service, shipped as one Docker image. It registers itself with the Bump directory using your organization key, and once Bump activates it the app can route users through it. Plan on about 30 minutes the first time.

What you need

A Linux host with a public IPv4 address (a small VPS is fine; IPv6 is a bonus). The server uses network_mode: host, so it does not run on Docker Desktop for Mac or Windows without extra port forwarding.
Docker Engine 24+ with the Compose plugin, and curl.
A hostname you control (for example vpn1.example.org) with an A record pointing at the host. Let's Encrypt issues the certificate automatically, so the name must resolve publicly before you start.
Inbound UDP 1194 (OpenVPN), TCP 443 (credentials over HTTPS) and, briefly, TCP 80 (certificate issuance) open on the host firewall and any router in front of it.
Your organization id (c-…) and API key (bvk_…) from the dashboard. The key is shown once when created or rotated.

1. Get the server files

Two files, served by this console for the vpn-directory.bumpapp.xyz directory. The image is public and has the OpenVPN config and helper scripts baked in, so this is all a server needs:

mkdir bump-vpn && cd bump-vpn
curl -fsSO https://operators.bumpapp.xyz/docs/docker-compose.yml
curl -fsS -o .env https://operators.bumpapp.xyz/docs/env

2. Configure

Edit .env and set these; leave everything else at its default:

VIRTUAL_HOST=vpn1.example.org
LETSENCRYPT_HOST=vpn1.example.org

BUMP_DIRECTORY_ORGANIZATION=c-your-organization-id
BUMP_DIRECTORY_API_KEY=bvk_your-key

The key is per organization, not per server. Every server you run shares it, and rotating it in the dashboard invalidates the old one immediately, so update each server's .env and restart it right after a rotation.

3. Start

Nothing to build: the compose file pulls the published image and runs Watchtower, which keeps the server on the latest release:

docker compose up -d

The first start takes a minute or two: OpenVPN generates its keys and Let's Encrypt issues the certificate. Follow along with:

docker compose logs -f openvpn-server

4. Check it

curl https://vpn1.example.org/health answers 200 once the certificate is in place.
Within a minute the server appears on your dashboard marked Pending activation. If it does not, the logs above will show why; the usual cause is a wrong organization id or key (the directory answers UNAUTHENTICATED).
Bump reviews and activates new servers. Once active, the app can select it and the dashboard shows it as online with its last health report.

Keeping it running

Updates arrive through Watchtower; nothing to do. To restart by hand: docker compose restart openvpn-server.
Identity lives in openvpn/keys/server-id. Keep that folder; deleting it registers a new server and orphans the old record.
Moving hosts: copy the whole bump-vpn folder (.env, openvpn/keys, nginx), update the DNS record, start on the new host.
Custom OpenVPN config: put your server.conf at openvpn/server.conf and uncomment its mount in docker-compose.yml; the one baked into the image is used otherwise.
Removing a server from the dashboard only deletes its record here; stop the container too, or it re-registers on its next health report.

Troubleshooting

Symptom	Check
Never shows up on the dashboard	`docker compose logs openvpn-server \| grep -i directory`. `UNAUTHENTICATED` means the organization id or key is wrong; a connection error means the host cannot reach `vpn-directory.bumpapp.xyz` on 443.
Certificate never issues	The hostname must resolve to this host from the internet and TCP 80 must be reachable. `docker compose logs letsencrypt` shows the challenge result.
Shows online but the app cannot connect	UDP 1194 is blocked somewhere. Test from outside: `nc -vzu vpn1.example.org 1194`.
Marked DNS on the dashboard	The hostname resolves to a different address than the one the server reports. Fix the A/AAAA record; the check repeats every few minutes.

Uplink capacity and Datadog log shipping are optional settings documented inline in .env. IPv6 works when the host has a public IPv6 address (the server listens dual-stack); add an AAAA record for the hostname.