3. Manager Setup

CompassVPN can send metrics to a central manager for monitoring and visualization. This guide explains how to set up the manager component, which is separate from the agent that runs on your VPN server.

Manager Options

CompassVPN supports two options for metrics collection and visualization:

1. Grafana Cloud (recommended for simplicity)
2. Self-hosted Prometheus + Pushgateway + Grafana on Kubernetes

Choose the option that best suits your needs based on your infrastructure and requirements.

Option 1: Grafana Cloud

Grafana Cloud offers a free tier that is sufficient for monitoring several CompassVPN agents.

Step 1: Create a Grafana Cloud Account

1. Go to Grafana Cloud and sign up for a free account
2. Verify your email address and complete the registration process

Step 2: Create a New Connection

1. After creating your account, go to the following URL (replace <your-username> with your actual Grafana Cloud username):

   https://<your-username>.grafana.net/connections/add-new-connection/hmInstancePromId

2. Create a new token as shown in the image below:

   

3. After creating the token, you’ll see three credentials as shown below:

   

4. Copy these three credentials:

   • URL
   • Username
   • Password

   These will be used in your agent configuration.

Step 3: Configure CompassVPN Agent

Now, add these credentials to your CompassVPN agent’s configuration using the Web Panel:

1. Access your agent’s Web Panel (refer to the Quick Start Guide if needed).
2. Navigate to the Monitoring section (or similar, depending on the panel layout).
3. Set the Metric Push Method to grafana_agent.
4. Enter the URL, Username, and Password you copied from Grafana Cloud into the corresponding fields.
5. Ensure any other required settings in the Web Panel are correctly configured.
6. Click the “Save, Close & Start” button. This will save the complete configuration to the env_file and automatically start or restart the CompassVPN agent service.

For detailed explanations of all parameters available in the Web Panel, see the Configuration Guide .

Step 4: Import Dashboards

1. In Grafana Cloud, navigate to Dashboards in the left sidebar

2. Click the Import button

3. Use the following dashboard ID:

   • 23181 for CompassVPN Dashboard

4. Set your prometheus data source

   Note: Dashboard page is available here .

Option 2: Self-hosted Kubernetes Deployment

This option gives you complete control over your monitoring stack but requires a Kubernetes cluster and more setup.

Repository Structure

The CompassVPN manager repository contains the following key components:

• prometheus/ - Helm chart values for Prometheus
• grafana/ - Helm chart values for Grafana
• nginx-ingress-controller/ - Helm chart values for NGINX Ingress
• create_auth.sh - Script to create basic authentication credentials
• auth.example - Example authentication file
• users.txt.example - Example users file

Step 1: Set Up a Kubernetes Cluster

Ensure you have a running Kubernetes cluster and can retrieve the list of nodes:

kubectl get nodes

Step 2: Add Required Helm Chart Repositories

helm repo add grafana https://grafana.github.io/helm-charts

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

Step 3: Create Authentication for Prometheus Pushgateway

1. Create a basic authentication file using the provided script or manually:

# Create auth file using the script
./create_auth.sh

# Or manually create it
htpasswd -c auth <username>

2. Create a Kubernetes secret from the authentication file:

kubectl create secret generic basic-auth --from-file=auth

You can refer to auth.example and users.txt.example in the repository for reference formats.

Step 4: Install Prometheus

Navigate to the prometheus directory and install using Helm:

cd prometheus/
helm install prometheus prometheus-community/prometheus -f values.yaml

Step 5: Install Grafana

Navigate to the grafana directory and install using Helm:

cd grafana/

helm install grafana grafana/grafana -f values.yaml

Step 6: Install NGINX Ingress Controller

Navigate to the nginx-ingress-controller directory and install using Helm:

cd nginx-ingress-controller/

helm install nginx-ingress-controller oci://registry-1.docker.io/bitnamicharts/nginx-ingress-controller -f values.yaml

Step 7: Configure CompassVPN Agent

Add your Pushgateway details to your CompassVPN agent’s configuration using the Web Panel:

1. Access your agent’s Web Panel.
2. Navigate to the Monitoring section (or similar).
3. Set the Metric Push Method (METRIC_PUSH_METHOD) to pushgateway.
4. Enter your Pushgateway URL, Username, and Password into the corresponding fields (PUSHGATEWAY_URL, PUSHGATEWAY_AUTH_USER, PUSHGATEWAY_AUTH_PASSWORD).
5. Ensure any other required settings in the Web Panel are correctly configured.
6. Click the “Save, Close & Start” button. This will save the complete configuration to the env_file and automatically start or restart the CompassVPN agent service.

For detailed explanations of all parameters available in the Web Panel, see the Configuration Guide .

Step 8: Import Dashboards in Grafana

1. Access Grafana at your configured ingress URL
2. Log in with your Grafana credentials (check the Grafana Helm values for default credentials)
3. Import the JSON dashboards:
   • Navigate to Dashboards > Import
   • Use dashboard ID 23181
   • Select your Prometheus data source
   • Click Import

Monitoring Multiple Agents

Both Grafana Cloud and the self-hosted solution support monitoring multiple CompassVPN agents. Each agent will be identified by its DONOR value in the env_file.

To distinguish between agents in dashboards, use the DONOR label as a filter variable.

Next Steps

After setting up your manager and configuring the agent via the Web Panel, the panel will automatically restart the agent when you use the appropriate action (Bootstrap, Restart, or Update) after saving. Metrics should start appearing in your Grafana instance shortly.

Note: Allow at least 5 minutes after the agent restarts for all logs and services to fully populate and stabilize. This ensures that metrics data starts flowing correctly to your manager.

Your CompassVPN installation is now complete and ready for use. You can access your monitoring dashboard and begin managing your VPN service through the configured interface.

For detailed information about using CompassVPN, please refer to our User Guide .