CustomVPN

Self-hosted WireGuard + AdGuard stack with one-command setup on Ubuntu 24.04.

CustomVPN works on any cloud provider (DigitalOcean, AWS, GCP, Azure, Hetzner, Vultr, etc.) and any region. Pick the region based on the egress location you want.

What You Get

• WireGuard VPN server on your VPS
• DNS ad/tracker blocking with AdGuard Home
• Private-by-default dashboards (access via SSH tunnel)
• Weekly updates + nightly backups (via systemd timers)

Prerequisites

• A VPS running Ubuntu 24.04 (1 vCPU / 1 GB RAM minimum)
• SSH access to the server
• Cloud firewall/security group allows:
  • 22/tcp
  • 51820/udp

Step-by-Step Setup

1. Create a VPS

Create an Ubuntu 24.04 VPS on any provider and note its public IP.

2. SSH into the server

ssh root@YOUR_SERVER_IP

3. Clone this repo

git clone https://github.com/YOUR_USERNAME/customvpn.git /opt/customvpn
cd /opt/customvpn

4. Choose image mode and run setup

Option A (default, recommended): use prebuilt upstream images

chmod +x setup.sh
./setup.sh --quick --use-prebuilt-images

Option B: build images locally from this repo, then run them

chmod +x setup.sh
./setup.sh --quick --build-local-images

What setup does:

• installs Docker + required tools
• configures firewall and host settings
• generates .env interactively
• starts wg-easy + adguard
• either pulls prebuilt images or builds local images (based on your option)
• installs update/backup timers

5. Open dashboards through SSH tunnel (recommended)

On your local machine:

ssh -L 51821:127.0.0.1:51821 -L 3000:127.0.0.1:3000 root@YOUR_SERVER_IP

Then open:

• http://127.0.0.1:51821 (wg-easy)
• http://127.0.0.1:3000 (AdGuard)

Windows PowerShell (OpenSSH) uses the same command.

6. Add your first device

1. Open wg-easy: http://127.0.0.1:51821
2. Click + New
3. Enter a device name
4. Scan QR with WireGuard app

7. Verify everything is healthy

/opt/customvpn/scripts/healthcheck.sh

Device Onboarding Notes

• iPhone/iPad: install WireGuard app, scan QR
• Android: install WireGuard app, scan QR
• Mac/Windows/Linux: install WireGuard desktop app, import config/QR
• Apple TV (tvOS 17+): install WireGuard app, import profile

Public Dashboards (Advanced)

Default mode keeps dashboards local-only. To expose dashboards publicly:

cd /opt/customvpn
./setup.sh --advanced --public-dashboards --regen-env

You must provide an IP/CIDR allowlist during env generation.

Switch Image Mode Later

To switch between prebuilt and local-build modes, regenerate .env:

cd /opt/customvpn
./setup.sh --regen-env --use-prebuilt-images
# or
./setup.sh --regen-env --build-local-images

Common Commands

• Stack status:

  cd /opt/customvpn && docker compose ps

• Logs:

  cd /opt/customvpn && docker compose logs -f --tail=200

• Health check:

  /opt/customvpn/scripts/healthcheck.sh

• Manual update:

  /opt/customvpn/scripts/update.sh

• Backup now:

  /opt/customvpn/scripts/backup.sh

• Restore backup:

  /opt/customvpn/scripts/restore.sh --file /path/to/backup.tar.gz.enc --yes

Scheduled Jobs Installed by Setup

• customvpn-update.timer (weekly updates)
• customvpn-backup.timer (nightly backup)
• customvpn-docker-fw.service (Docker firewall policy)

Check timers:

systemctl list-timers | grep customvpn

Backup Configuration

Create /etc/customvpn/backup.env:

cat >/etc/customvpn/backup.env <<'EOFCONF'
BACKUP_DIR=/var/backups/customvpn
BACKUP_PASSPHRASE=CHANGE_ME
# scp destination OR rclone remote (prefix with rclone:)
OFFSITE_TARGET=user@backup-host:/srv/customvpn/
EOFCONF
chmod 600 /etc/customvpn/backup.env

Troubleshooting

VPN connects but no internet

docker inspect customvpn-adguard --format '{{.State.Health.Status}}'
dig @10.8.1.10 google.com

Dashboard not loading

• Verify SSH tunnel is still active
• Check .env values: WG_UI_BIND, ADGUARD_UI_BIND

Password/hash issues

cd /opt/customvpn
./setup.sh --regen-env

Re-apply Docker firewall policy

systemctl restart customvpn-docker-fw.service

Uninstall

cd /opt/customvpn
./setup.sh --uninstall