Quickstart

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.

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.

Note: all the commands below are expected to be run as root.

Step 0: Install PostgreSQL (optional)

This is to be run on the controller server

The controller needs a PostgreSQL database, which can be either local to the brainz service, or remote, such as RDS.

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

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

# Set timezone parameter to UTC
sed -i -e "s/#\?timezone .*/timezone = 'UTC'/g" /etc/postgresql/18/main/postgresql.conf
systemctl restart postgresql

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

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

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

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

# Set timezone parameter to UTC
sed -i -e "s/#\?timezone .*/timezone = 'UTC'/g" /var/lib/pgsql/18/data/postgresql.conf

# Enable and start PostgreSQL
systemctl enable postgresql-18
systemctl start postgresql-18

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

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

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

# Restart PostgreSQL
systemctl restart postgresql-18

Step 1: Set up the repository for Varnish Controller components

This is to be run on all instances

apt update
apt install -y curl
curl -s https://packagecloud.io/install/repositories/varnishplus/60-enterprise/script.deb.sh | bash

curl -s https://packagecloud.io/install/repositories/varnishplus/60-enterprise/script.rpm.sh | bash

Step 2: Install the `controller` node

This is to be run on the controller instance

# Install and start NATS
apt install -y varnish-controller-api-gw varnish-controller-brainz varnish-controller-cli varnish-controller-nats varnish-controller-ui

# Install
dnf -y install varnish-controller-api-gw varnish-controller-brainz varnish-controller-cli varnish-controller-nats varnish-controller-ui

License

Place the controller license (it should start with a product: Varnish Controller line):

cp varnish-controller.lic /var/lib/varnish-controller/varnish-controller-brainz/varnish-controller.lic

Brainz

Brainz is the service that interacts with the PostgreSQL database, so you need to fill in the proper credentials in the following instructions.

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

mkdir -p /etc/systemd/system/varnish-controller-brainz.service.d
cat << EOF > /etc/systemd/system/varnish-controller-brainz.service.d/override.conf
[Service]
Environment="VARNISH_CONTROLLER_MOD_ADMIN_USER=true"
Environment="VARNISH_CONTROLLER_SYSTEM_ADMIN_USER=admin"
Environment="VARNISH_CONTROLLER_SYSTEM_ADMIN_PASS=<new_password>"
Environment="VARNISH_CONTROLLER_NATS_SERVER=localhost:4222"
Environment="VARNISH_CONTROLLER_DB_NAME=varnishcontroller"
Environment="VARNISH_CONTROLLER_DB_USER=varnishcontroller"
Environment="VARNISH_CONTROLLER_DB_PASS=<your_db_pass>"

# for an RDS database, you can also use those variables:
# Environment="VARNISH_CONTROLLER_DB_SERVER=<rds_host>"
# Environment="VARNISH_CONTROLLER_DB_SSL=verify-full"
# global-bundle.pem downloaded from https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem
# Environment="VARNISH_CONTROLLER_DB_SSL_ROOT=/etc/varnish/global-bundle.pem"
EOF

systemctl daemon-reload
systemctl restart varnish-controller-brainz

API gateway

The API gateway just needs to connect to the NATS server, which in this case is on localhost:4222, the default, so there’s no specific configuration for it, but you can find more options in the API-GW installation page

Graphical User Interface (optional)

The controller provides a Web interface that is useful to explore the various features of the platform.

The following configuration open the UI on the default port, 8080, without TLS:

mkdir -p /etc/systemd/system/varnish-controller-ui.service.d
cat << EOF > /etc/systemd/system/varnish-controller-ui.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/varnish-controller-ui -api-hosts=http://localhost:8002 -no-tls
EOF

systemctl daemon-reload
systemctl restart varnish-controller-ui

You can find more information in UI installation page

Step 3: Varnish and agent

This is to be run on the varnish instances

First, install Varnish.

Then install the agent:

apt install -y varnish-controller-agent

dnf -y install varnish-controller-agent

Lastly, we want to configure the varnish-controller-agent to connect to the NATS server we installed in steps 2 and 3. For this you need to set VARNISH_CONTROLLER_NATS_SERVER to the address of the controller address.

mkdir -p /etc/systemd/system/varnish-controller-agent.service.d
cat << EOF > /etc/systemd/system/varnish-controller-agent.service.d/override.conf
[Service]
# clear VARNISH_CONTROLLER_AGENT_NAME so the hostname is used automatically for it
Environment="VARNISH_CONTROLLER_AGENT_NAME="
Environment="VARNISH_CONTROLLER_NATS_SERVER=<controller_server_address>:4222"
EOF

systemctl daemon-reload
systemctl enable varnish varnish-controller-agent
systemctl restart varnish varnish-controller-agent

Step 4: Verify installations

This is to be run on the controller instance

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

vcli login http://localhost:8002 -u admin
Password: <new_password>
vcli agent ls

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

Step 5: 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
apt install varnish-controller-router

# Configure NATS for the router by editing systemd unit file.
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"

# Enable and restart the router
systemctl enable varnish-controller-router
systemctl restart varnish-controller-router

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

# Configure NATS for the router by editing the systemd unit file.
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"

# Enable, and start
systemctl enable varnish-controller-router
systemctl restart varnish-controller-router

Step 6: Verify Router installation