Installation

Setting up CompassVPN takes about fifteen minutes on a small rented server (a VPS). Make sure your server meets the requirements below, then work through the guides in order:

Quick Start
- Prepare the server, deploy the agent, and get your VPN configuration links.
Configuration
- Reference for every env_file parameter, to tailor CompassVPN to your requirements.
Monitoring
- Create your Grafana dashboard and the metrics credentials the agent needs.

Requirements

Before installing CompassVPN, ensure your Linux system meets the following requirements:

VPS Architecture: AMD64 or ARM64 (recommended: 2 vCPUs and 2GB RAM)
Supported Operating Systems: CompassVPN is tested and optimized for these distributions.
- Ubuntu (22.04 LTS or newer)
- Debian (11 or newer)
Root access: The agent must be deployed as root (or through sudo).
Required packages: git and curl
Open ports: The agent configures the UFW firewall itself, opening TCP and UDP on ports 80, 443, 2053, 2083, 2087, 8080, 8443, 8880 plus your SSH port. If your provider has an external firewall or security group (common on cloud VPS), allow the same ports there. The metrics ports stay bound to loopback and need no rules.
Domain Name: A domain name is required for SSL certificate generation and secure access.
- Must be a valid, registered domain on your Cloudflare account.
- Common TLDs such as .com, .org, .co, .net, .info, and .ir work well.
- Cheap or free domains may be blocked by firewalls more quickly.

Ready? Begin with the Quick Start guide.