Public | Automated Build

Last pushed: 2 years ago
Short Description
Etcd aware daemon for configuring Varnish
Full Description


Etcd aware daemon for configuring Varnish

Heliumd stores Varnish configuration inside Etcd, listens for changes and reconfigures Varnish. It is intended to be used in a Dockerized environment and can be used alongside a service such as registrator.

Starting Heliumd

Heliumd starts with sane defaults. It expects Varnish to be running on the same host with the admin interface running on port 6082. It will write two files by default, /etc/varnish/directors.vcl and /etc/varnish/default.vcl. All defaults can be overriden, you can see a list by running heliumd with --help.

To start Heliumd you must provide the address to a working Etcd instance.

$ ./heliumd

Running the Docker container

This repository contains a working Dockerfile, it exposes the web interface on port 80 and the admin interface on port 6082. To get things up and running you simply run:

$ docker run -d -P -e ETCD_PEER= iainmckay/heliumd

The container can be customized with these environment variables:

Name | Default Value | Description
ETCD_KEY | /varnish | Which Etcd path to watch for configuration
ETCD_PEER | | The Etcd peer to connect to
OUT_DIRECTORS | /etc/varnish/directors.vcl | Where to output the directors
OUT_VCL | /etc/varnish/default.vcl | Where to output the main VCL
VARNISH_ALLOCATION | 100m | How much memory to allocate to Varnish
VARNISH_SECRET | /etc/varnish/secret | Where to store the varnish secret

Adding hosts and upstreams

By default Heliumd will watch /varnish in Etcd for host and upstream changes. The expected format for host and upstreams is the same used in Vulcand so it is possible to run this in conjunction with Vulcand.

Adding hosts

Hosts consist of a domain, a path under that domain, a VCL and an upstream to route traffic to.

/varnish/hosts/ /some-super-service
/varnish/hosts/ super-service
/varnish/hosts/ passthrough

In this example, we are going to have Varnish route traffic for through an upstream called super-service and use a VCL called passthrough.

Heliumd is by default, opinionated, on how to setup Varnish. It supports being able to use a separate VCL per location. You can see a working example for passthrough in the VCL directory here. You could write the provided templates to not use this VCL setup.

Adding upstreams

Upstreams are a collection of backends to send traffic to.


Continuing the some-super-service example in the previous section. Here we register 3 backends on 3 different ports. Only HTTP is supported.

You can use a helper container such as registrator to manage these automatically. PR #53 adds support for the Vulcand format that Heliumd uses, it will hopefully be merged in to master soon.


It is recommended you run Nginx or another reverse-proxy in front of Varnish to provide SSL termination.

Docker Pull Command
Source Repository