Quickstart

Introduction

This is a step-by-step quickstart to install Varnish Controller the most basic way without any NATS encryption, etc. It is possible to 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 example system layout.

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

Installation

This guide will use two types of servers:

Controller server - Server where Varnish Controller specific components.
Varnish server - Server for 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 in order 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.

sudo apt update
sudo apt install -y apt-transport-https curl

# Add keys (change <token> to your packagecloud token for Varnish Controller
curl -L https://<token>:@packagecloud.io/varnishplus/controller/gpgkey | sudo apt-key add -

# Add repo (change <token> to your packagecloud token for Varnish Controller)
echo "deb https://<token>:@packagecloud.io/varnishplus/controller/debian/ stretch main" | sudo tee -a /etc/apt/sources.list.d/varnish-controller.list

# Fetch new package information
sudo apt update

Add the following to /etc/yum.repos.d/varnish-controller.repo (replace <token> with your package cloud token for Varnish Controller)

[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 yum clean all

Step 2: Install NATS

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

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

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

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

Step 3: Install PostgreSQL

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

# Install PostgreSQL
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update
sudo apt install -y postgresql-12

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

# Basic setup of the database
sudo su - postgres -c "/usr/lib/postgresql/12/bin/createuser -P varnishcontroller"
sudo su - postgres -c "/usr/lib/postgresql/12/bin/createdb -EUTF8 -l en_US.UTF-8 --template=template0 -O varnishcontroller varnishcontroller"
sudo su - postgres -c "/usr/lib/postgresql/12/bin/psql -U postgres -c 'GRANT ALL PRIVILEGES ON DATABASE varnishcontroller TO varnishcontroller'"

# Install PostgreSQL
sudo yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-7-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo yum -y install postgresql12-server postgresql12-contrib

# Set timezone to UTC
sudo sed -i -e "s/#timezone .*/timezone = 'UTC'/g" /var/lib/pgsql/12/data/pg_hba.conf

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

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

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

# Create a database called 'varnish-controller'
sudo su - postgres -c "/usr/pgsql-12/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/12/data/pg_hba.conf

# Restart PostgreSQL
sudo systemctl restart postgresql-12

Step 4: Install Brainz

Brainz is installed on the controller server.

Note that we configure Brainz to talk to the NATS server on localhost port 4222. This is the default host/port and we assume that the NATS server was installed on the controller server Step 2.

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 login with 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 are allowed 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 yum -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 login with 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 are allowed 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: Install 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 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 yum -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: Install Varnish

This is performed on the varnish server.

# Prepare (Debian Stretch example)
curl -L https://<varnish_pkgcloud_token>:@packagecloud.io/varnishplus/60/gpgkey | sudo apt-key add -
echo "deb https://<varnish_pkgcloud_token>:@packagecloud.io/varnishplus/60/debian/ stretch main" |sudo tee -a /etc/apt/sources.list.d/varnish-enterprise-6.0.list

# 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. Replace <varnish_token> with your Varnish Enterprise token for packagecloud.

[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 yum clean all
sudo yum -y install varnish-plus

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

Step 7: Install Agent

This is installed on the varnish server. Note that we 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 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 yum -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: Install Varnish Controller CLI

This step is optional, but recommended. The CLI can be installed on any computer to access the Varnish Controller system. In this guide we install it on the controller server for easy access towards the 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 yum -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: ****

Verify Installation

If everything went right you will see something like this using 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    |      |
+----+---------+---------+--------------+-----------------+------+

Optional Router Installation

The router is an optional component that 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. The license file itself requires a router add-on for the router to fully operate.

The router can be installed on any server. Do note that depending on amount of traffic, this can be quite resources intensive when it comes to CPU usage.

Note that we 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 yum -y 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_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

Verify Router Installation

If everything went right you will see something like this using 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 |        |
+----+---------+---------+-------+------+--------+