Quickstart

Introduction

This is a step-by-step guide to installing Varnish Controller in the most basic way without any NATS encryption, etc. You can run all the processes on the same host for testing, as in this guide, but it is not recommended in production. See the system overview for an example system layout.

The default parameters for the Varnish Controller binaries are based on default values for NATS, PostgreSQL, and Varnish. This quickstart guide assumes that these are not changed.

Installation

This guide will use two types of servers:

Controller server - Server for specific components of Varnish Controller
Varnish server - Server for the Varnish Cache and Varnish Controller Agent

The installation of all components can be performed on one server for testing. The recommended setup is to have at least one controller server and a separate varnish server for each Varnish/Agent instance.

Since all Varnish Controller components can scale horizontally, there can be more than one controller server, but to make this guide simple, it only aims for one controller server.

Step 1: Set up the repository for Varnish Controller

This step is performed on both controller servers and varnish servers.

Note: Replace with your Varnish Controller packagecloud token.

sudo apt update
sudo apt install -y gpg sudo wget

# Add keys 
wget --auth-no-challenge --quiet -O - https://<token>:@packagecloud.io/varnishplus/controller/gpgkey | \
    sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/varnish-controller.gpg

# Add repo
echo "deb [signed-by=/etc/apt/trusted.gpg.d/varnish-controller.gpg] https://packagecloud.io/varnishplus/controller/debian/ stretch main" | \
    sudo tee -a /etc/apt/sources.list.d/varnish-controller.list

# Add authentication info for the repo
echo -e "machine packagecloud.io/varnishplus/controller\nlogin <token>" | \
    sudo tee /etc/apt/auth.conf.d/varnish-controller.conf

# Fetch new package info
sudo apt update

Add the following to /etc/yum.repos.d/varnish-controller.repo

[varnish-controller]
name=varnish-controller
baseurl=https://<token>:@packagecloud.io/varnishplus/controller/el/$releasever/$basearch
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://<token>:@packagecloud.io/varnishplus/controller/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

sudo dnf clean all

Step 2: NATS

This is installed on the controller server, but can be installed on any server for NATS redundancy. See NATS Clustering for more info.

# Install and start NATS
sudo apt install varnish-controller-nats

# Make sure network-online is active
sudo systemctl status network-online.target

# If not, start it
sudo systemctl start network-online.target

# Enable & start NATS
sudo systemctl enable varnish-controller-nats
sudo systemctl start varnish-controller-nats

# Install
sudo dnf -y install varnish-controller-nats

# Enable and start
sudo systemctl enable varnish-controller-nats
sudo systemctl start varnish-controller-nats

Step 3: PostgreSQL

For a more comprehensive (and recommended) setup, follow the PostgreSQL installation guide.

# Install PostgreSQL
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
# Install PostgreSQL:
sudo apt -y install postgresql-17

# Set timezone to UTC
sudo sed -i -e "s/#timezone .*/timezone = 'UTC'/g" /etc/postgresql/17/main/postgresql.conf
sudo systemctl restart postgresql

# Setup a user called 'varnish-controller'
# It will ask you to enter a password for this user.
sudo su - postgres -c "/usr/lib/postgresql/17/bin/createuser -P varnishcontroller"

# Create a database called 'varnish-controller'
sudo su - postgres -c "/usr/lib/postgresql/17/bin/createdb -EUTF8 -l en_US.UTF-8 --template=template0 -O varnishcontroller varnishcontroller"
sudo su - postgres -c "/usr/lib/postgresql/17/bin/psql -U postgres -c 'GRANT ALL PRIVILEGES ON DATABASE varnishcontroller TO varnishcontroller'"

# Install PostgreSQL
# Tested on  Alma Linux 9 / Rocky Linux 9
sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf -y install postgresql17-server postgresql17-contrib

# Set timezone to UTC
sudo sed -i -e "s/#timezone .*/timezone = 'UTC'/g" /var/lib/pgsql/17/main/postgresql.conf

# Set up database
sudo PGSETUP_INITDB_OPTIONS="-k -EUTF8 --locale=en_US.utf8" /usr/pgsql-17/bin/postgresql-17-setup initdb

# Enable and start PostgreSQL
sudo systemctl enable postgresql-17
sudo systemctl start postgresql-17

# Set up a user called 'varnish-controller'
# Enter a password
sudo su - postgres -c "/usr/pgsql-17/bin/createuser -P varnishcontroller"

# Create a database called 'varnish-controller'
sudo su - postgres -c "/usr/pgsql-17/bin/createdb -EUTF8 -l en_US.utf8 -O varnishcontroller varnishcontroller"

# Change authentication method from ident to md5
sudo sed -i -e 's%ident%md5%g' /var/lib/pgsql/17/data/pg_hba.conf

# Restart PostgreSQL
sudo systemctl restart postgresql-17

Step 4: Brainz

Brainz is installed on the controller server. Brainz will be configured to talk to the NATS server on localhost port 4222 (the default host/port). This assumes that the NATS server was installed on the controller server.

Details about system admin creation can be found in the authentication chapter.

sudo apt install varnish-controller-brainz

# Edit the systemd unit file to set password
sudo systemctl edit varnish-controller-brainz

# Add the following (replace your DB password)
# The username and password for admin will be the user that
# you use to login to the Varnish Controller (with full access).
[Service]
Environment="VARNISH_CONTROLLER_DB_NAME=varnishcontroller"
Environment="VARNISH_CONTROLLER_DB_PASS=<your_db_pass>"
Environment="VARNISH_CONTROLLER_DB_USER=varnishcontroller"
Environment="VARNISH_CONTROLLER_MOD_ADMIN_USER=true"
Environment="VARNISH_CONTROLLER_SYSTEM_ADMIN_USER=<new_username>"
Environment="VARNISH_CONTROLLER_SYSTEM_ADMIN_PASS=<new_password>"
Environment="VARNISH_CONTROLLER_NATS_SERVER=localhost:4222"

# Add your personal Varnish Controller license file
# (make sure Brainz is authorized to read the license file)
cp customer.lic /var/lib/varnish-controller/varnish-controller-brainz/varnish-controller.lic

# Reload override for systemd and start Brainz
sudo systemctl daemon-reload
sudo systemctl start varnish-controller-brainz

sudo dnf -y install varnish-controller-brainz

# Edit the systemd unit file to set password
sudo systemctl edit varnish-controller-brainz

# Add the following (replace your DB password)
# The username and password for admin will be the user that
# you use to login to the Varnish Controller (with full access).
[Service]
Environment="VARNISH_CONTROLLER_DB_NAME=varnishcontroller"
Environment="VARNISH_CONTROLLER_DB_PASS=<your_db_pass>"
Environment="VARNISH_CONTROLLER_DB_USER=varnishcontroller"
Environment="VARNISH_CONTROLLER_MOD_ADMIN_USER=true"
Environment="VARNISH_CONTROLLER_SYSTEM_ADMIN_USER=<new_username>"
Environment="VARNISH_CONTROLLER_SYSTEM_ADMIN_PASS=<new_password>"
Environment="VARNISH_CONTROLLER_NATS_SERVER=localhost:4222"

# Add your personal Varnish Controller license file
# (make sure Brainz is authorized to read the license file)
cp customer.lic /var/lib/varnish-controller/varnish-controller-brainz/varnish-controller.lic

# Start Brainz with default values except for user/pass for the database
sudo systemctl daemon-reload
sudo systemctl enable varnish-controller-brainz
sudo systemctl start varnish-controller-brainz

Step 5: API-GW

This is installed on the controller server. NATS is configured towards the same host.

# Install and start API-GW
sudo apt install varnish-controller-api-gw

# Edit the systemd unit file for API-GW to specify the NATS-server
sudo systemctl edit varnish-controller-api-gw

# Add the following
[Service]
Environment="VARNISH_CONTROLLER_NATS_SERVER=localhost:4222"

# Reload and restart API-GW
sudo systemctl daemon-reload
sudo systemctl start varnish-controller-api-gw

# Install and start API-GW
sudo dnf -y install varnish-controller-api-gw

# Edit the systemd unit file for API-GW to specify NATS-server
sudo systemctl edit varnish-controller-api-gw

# Add the following
[Service]
Environment="VARNISH_CONTROLLER_NATS_SERVER=localhost:4222"

# Reload, enable, and start
sudo systemctl daemon-reload
sudo systemctl enable varnish-controller-api-gw
sudo systemctl start varnish-controller-api-gw

Step 6: Varnish

This is performed on the varnish server.

Note: Replace with your Varnish Controller packagecloud token.


# Prepare (Debian Stretch example)
# Add keys 
wget --auth-no-challenge --quiet -O - https://<varnish_enterprise_token>:@packagecloud.io/varnishplus/60/gpgkey | \
    sudo sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/varnish-enterprise-6.0.gpg

# Add repo
echo "deb [signed-by=/etc/apt/trusted.gpg.d/varnish-enterprise-6.0.gpg] https://packagecloud.io/varnishplus/60/debian/ stretch main" | \
    sudo tee -a /etc/apt/sources.list.d/varnish-enterprise.list

# Add authentication information for the repo
echo -e "machine packagecloud.io/varnishplus/60\nlogin <varnish_enterprise_token>" | \
    sudo tee /etc/apt/auth.conf.d/varnish-controller.conf

# Install
sudo apt update
sudo apt install -y varnish-plus

Add the following to the file /etc/yum.repos.d/varnish-enterprise-6.0.repo.

[varnish-enterprise-60]
name=varnish-enterprise-60
baseurl=https://<varnish_token>:@packagecloud.io/varnishplus/60/el/$releasever/$basearch
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://<varnish_token>:@packagecloud.io/varnishplus/60/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

# Update repo and install varnish-plus
sudo dnf clean all
sudo dnf -y install varnish-plus

# Enable and start
sudo systemctl enable varnish
sudo systemctl start varnish

Step 7: Agent

This is installed on the varnish server. You’ll need to configure NATS to talk to the NATS-server on the controller server.

# Install and start the agent
sudo apt install varnish-controller-agent

# Configure NATS for the agent by editing the systemd unit file.
sudo systemctl edit varnish-controller-agent

# Add the following
[Service]
Environment="VARNISH_CONTROLLER_AGENT_NAME=agent01"
Environment="VARNISH_CONTROLLER_NATS_SERVER=controller-host:4222"
Environment="VARNISH_CONTROLLER_BASE_URL=http://agent01.example.com"

# Reload and restart the agent
sudo systemctl daemon-reload
sudo systemctl start varnish-controller-agent

# Install and start the agent
sudo dnf -y install varnish-controller-agent

# Configure NATS for the agent by editing systemd unit file.
sudo systemctl edit varnish-controller-agent

# Add the following
[Service]
Environment="VARNISH_CONTROLLER_AGENT_NAME=agent01"
Environment="VARNISH_CONTROLLER_NATS_SERVER=controller-host:4222"
Environment="VARNISH_CONTROLLER_BASE_URL=http://agent01.example.com"

# Reload, enable, and start
sudo systemctl daemon-reload
sudo systemctl enable varnish-controller-agent
sudo systemctl start varnish-controller-agent

Step 8: Varnish Controller CLI (optional)

This step is recommended. The CLI can be installed on any computer to access the Varnish Controller system. Here you will install it on the controller server for easy access to Varnish Controller.

sudo apt install varnish-controller-cli

# Login to the API-GW using the user and password added in Step 3.
# Organization can be anything for a system admin user ('test' used in this case).
vcli login http://localhost:8002 -u <user>
Password: ****

sudo dnf -y install varnish-controller-cli

# Login to the API-GW using the user and password added in Step 3.
# Organization can be anything for a system admin user ('test' used in this case).
vcli login http://localhost:8002 -u <user>
Password: ****

Step 9: Varnish Controller GUI (optional)

The GUI can be installed on any computer to access the Varnish Controller system. Here, you’ll install it on the controller server for easy access to Varnish Controller.

sudo apt install varnish-controller-ui

# the API host can be changed if not installed on the controller server
sudo systemctl edit varnish-controller-agent

sudo systemctl daemon-reload
sudo systemctl restart varnish-controller-ui

sudo dnf -y install varnish-controller-ui

# the API host can be changed if not installed on the controller server
sudo systemctl edit varnish-controller-agent

sudo systemctl daemon-reload
sudo systemctl restart varnish-controller-ui

Step 10: Verify installations

If everything worked, you’ll see something like this in the Varnish Controller CLI on the controller server:

# Execute command
vcli agent ls

# Expected output
+----+---------+---------+--------------+-----------------+------+
| ID |  Name   |  State  | Varnish Host | Varnish Version | Tags |
+----+---------+---------+--------------+-----------------+------+
|  1 | agent01 | Running | 10.0.2.15    | plus-6.0.6r5    |      |
+----+---------+---------+--------------+-----------------+------+

Step 11: Router (optional)

The router can be used for traffic routing. For detailed setup and DNS configuration, see Router Installation. The router requires a valid Varnish Controller license, loaded in Brainz, to work. Also, the license file requires a router add-on for the router to fully operate.

The router can be installed on any server and, depending on the amount of traffic, it can be quite resource-intensive when it comes to CPU usage.

You’ll need to configure NATS to talk to the NATS-server on the controller server.

# Install and start the router
sudo apt install varnish-controller-router

# Configure NATS for the router by editing systemd unit file.
sudo systemctl edit varnish-controller-router

# Add the following (enabled both HTTP and DNS routing)
[Service]
Environment="VARNISH_CONTROLLER_ROUTER_NAME=router1"
Environment="VARNISH_CONTROLLER_HTTP_ROUTING=true"
Environment="VARNISH_CONTROLLER_NATS_SERVER=controller-host:4222"

# Reload and restart the router
sudo systemctl daemon-reload
sudo systemctl start varnish-controller-router

# Install and start the router
sudo dnf -y install varnish-controller-router

# Configure NATS for the router by editing the systemd unit file.
sudo systemctl edit varnish-controller-router

# Add the following (enabled both HTTP and DNS routing)
[Service]
Environment="VARNISH_CONTROLLER_ROUTER_NAME=router1"
Environment="VARNISH_CONTROLLER_HTTP_ROUTING=true"
Environment="VARNISH_CONTROLLER_DNS_ROUTING=true"
Environment="VARNISH_CONTROLLER_NATS_SERVER=controller-host:4222"

# Reload, enable, and start
sudo systemctl daemon-reload
sudo systemctl enable varnish-controller-router
sudo systemctl start varnish-controller-router

Step 12: Verify Router installation

If everything worked, you’ll see something like this in the Varnish Controller CLI on the controller server:

# Execute command
vcli router ls

# Expected output
+----+---------+---------+-------+------+--------+
| ID |  Name   |  State  |  DNS  | HTTP |  Tags  |
+----+---------+---------+-------+------+--------+
|  1 | router1 | Running | false | true |        |
+----+---------+---------+-------+------+--------+