Public | Automated Build

Last pushed: a year ago
Short Description
Alpine Linux, s6 process management running Consul.
Full Description


A Docker image for running consul, based on Alpine Linux.
This image belongs to a suite of images documented here.

Image size is ~36.9 MB.


This image features:


See for image contents.


To use this image include FROM smebberson/alpine-consul at the top of your Dockerfile, or simply docker run --name consul smebberson/alpine-consul.

By default, Consul has been configured with zero-conf Consul bootstrapping (to take advantage of zero-conf Consul bootstrapping, Docker 1.10+ is required).

To use this image to setup a Consul cluster with 3 nodes via Docker Compose, add the following to your docker-compose.yml file:

version: '2'

        image: smebberson/alpine-consul:dev

Then start with dc up -d && dc scale consul=3. You don't need to worry about bootstrapping the Consul cluster, everything just works.


This container comes setup as follows:

  • Consul will automatically start.
  • If Consul dies, it will automatically be restarted (the container will remain running).

All configuration has been defined in the root/etc/consul/conf.d/bootstrap/config.json file.

To customise configuration for consul, replace the file at root/etc/consul/conf.d/bootstrap/config.json with your own configuration.

To customise the start script for consul, replace the file at root/etc/services.d/consul/run with your own start script.

Consul DNS domain

By default, Consul's DNS domain is consul.. This allows you to make DNS queries such as nginx.service.consul to find all IPs relating to the nginx service (for example). Through customizing the environment variable CONSUL_DOMAIN you can alter Consul's DNS domain.

For example, add ENV CONSUL_DOMAIN=dockeralpine to your Dockerfile and you'll be able to make a DNS query for nginx.service.dockeralpine rather than the default.

You can read more about Consul's DNS interface here.

Consul DC

By default, Consul runs itself in data center dc1. Through customizing the environment variable CONSUL_DC you can alter Consul's data center configuration.

For example, ADD ENV CONSUL_DC=dc2 to your Dockerfile and you'll be able to make a DNS query for nginx.service.dc2.dockeralpine rather than the default.

Consul Advertise WAN

By default, Consul advertises itself with the address that it binds to. Within a container the bind address is Dockers private IP and in a multi data center setup that IP would not be reachable. Through customizing the environment variable CONSUL_ADVERTISE_WAN you can alter the IP Consul reports to WAN.

For example, docker run -e "CONSUL_ADVERTISE_WAN=ifconfig | grep -A 1 'ens4' | tail -1 | cut -d ':' -f 2 | cut -d ' ' -f 1" where ens4 is the interface with a reachable IP.

Consul join WAN

To join Consul server to through WAN to another Consul use environmental variable CONSUL_JOIN_WAN. Through customizing this environmental variable you can make Consul communicate across WAN.

For example, docker run -e "CONSUL_JOIN_WAN=" would make Consul reach out to and register itself with

Consul translate WAN

By default, Consul does not translate IPs when in WAN. Service discovery from dc1 will return private IPs of dc2. Through customizing the environment variable CONSUL_TRANSLATE_WAN you can make Consul to resolve to IP specified with CONSUL_ADVERTISE_WAN.

For example, docker run -e "CONSUL_TRANSLATE_WAN=true" Consul will resolve to IP defined with CONSUL_ADVERTISE_WAN.


The scripts involved in bootstrapping Consul can output debug information if required. To enable set CONSUL_BOOTSTRAP_DEBUG to true. You can customise the log file location from the default of /var/log/consul-bootstrap/consul-bootstrap.log by setting CONSUL_BOOTSTRAP_LOG_FILE.


An example of using this image can be found in examples/user-confd.

Docker Pull Command
Source Repository