[{"_1":2,"_175":-5,"_176":-5},"loaderData",{"_3":4,"_17":18,"_25":26,"_150":151},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","routes/_layout",{"_19":-5,"_20":21,"_22":21,"_23":11,"_24":21},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":-5,"_89":90,"_139":-5,"_140":11,"_141":21,"_142":11,"_143":-5,"_144":11,"_145":-5,"_146":147,"_148":91,"_149":-7},"canonicalUrl","https://hub.docker.com/r/civiclabs/consul/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","civiclabs","reponame","consul","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":-5,"_61":62,"_63":62,"_64":65,"_66":-5,"_67":68,"_69":70,"_71":11,"_72":33,"_73":74,"_79":21,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2016-07-09T17:34:29.981053Z","description","Consul","is_private","last_updated","2016-09-14T00:16:21.014371Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",696,"repository_type","star_count",1,"status","status_description","active","source","collaborator_count",0,"full_description","# Consul Agent in Docker\n\nThis project is a Docker container for [Consul](http://www.consul.io/). It's a slightly opinionated, pre-configured Consul Agent made specifically to work in the Docker ecosystem.\n\n## Getting the container\n\nThe container is very small (50MB virtual, based on [Busybox](https://github.com/progrium/busybox)) and available on the Docker Index:\n\n\t$ docker pull progrium/consul\n\n## Using the container\n\n#### Just trying out Consul\n\nIf you just want to run a single instance of Consul Agent to try out its functionality:\n\n\t$ docker run -p 8400:8400 -p 8500:8500 -p 8600:53/udp -h node1 progrium/consul -server -bootstrap\n\nThe [Web UI](http://www.consul.io/intro/getting-started/ui.html) can be enabled by adding the `-ui-dir` flag:\n\n\t$ docker run -p 8400:8400 -p 8500:8500 -p 8600:53/udp -h node1 progrium/consul -server -bootstrap -ui-dir /ui\n\nWe publish 8400 (RPC), 8500 (HTTP), and 8600 (DNS) so you can try all three interfaces. We also give it a hostname of `node1`. Setting the container hostname is the intended way to name the Consul Agent node. \n\nOur recommended interface is HTTP using curl:\n\n\t$ curl localhost:8500/v1/catalog/nodes\n\nWe can also use dig to interact with the DNS interface:\n\n\t$ dig @0.0.0.0 -p 8600 node1.node.consul\n\nHowever, if you install Consul on your host, you can use the CLI to interact with the containerized Consul Agent:\n\n\t$ consul members\n\n#### Testing a Consul cluster on a single host\n\nIf you want to start a Consul cluster on a single host to experiment with clustering dynamics (replication, leader election), here is the recommended way to start a 3 node cluster. \n\nHere we start the first node not with `-bootstrap`, but with `-bootstrap-expect 3`, which will wait until there are 3 peers connected before self-bootstrapping and becoming a working cluster.\n\n\t$ docker run -d --name node1 -h node1 progrium/consul -server -bootstrap-expect 3\n\nWe can get the container's internal IP by inspecting the container. We'll put it in the env var `JOIN_IP`.\n\n\t$ JOIN_IP=\"$(docker inspect -f '{{.NetworkSettings.IPAddress}}' node1)\"\n\nThen we'll start `node2` and tell it to join `node1` using `$JOIN_IP`:\n\n\t$ docker run -d --name node2 -h node2 progrium/consul -server -join $JOIN_IP\n\nNow we can start `node3` the same way:\n\n\t$ docker run -d --name node3 -h node3 progrium/consul -server -join $JOIN_IP\n\nWe now have a real three node cluster running on a single host. Notice we've also named the containers after their internal hostnames / node names.\n\nWe haven't published any ports to access the cluster, but we can use that as an excuse to run a fourth agent node in \"client\" mode (dropping the `-server`). This means it doesn't participate in the consensus quorum, but can still be used to interact with the cluster. It also means it doesn't need disk persistence.\n\n\t$ docker run -d -p 8400:8400 -p 8500:8500 -p 8600:53/udp --name node4 -h node4 progrium/consul -join $JOIN_IP\n\nNow we can interact with the cluster on those published ports and, if you want, play with killing, adding, and restarting nodes to see how the cluster handles it.\n\n#### Running a real Consul cluster in a production environment\n\nSetting up a real cluster on separate hosts is very similar to our single host cluster setup process, but with a few differences:\n\n * We assume there is a private network between hosts. Each host should have an IP on this private network\n * We're going to pass this private IP to Consul via the `-advertise` flag\n * We're going to publish all ports, including internal Consul ports (8300, 8301, 8302), on this IP\n * We set up a volume at `/data` for persistence. As an example, we'll bind mount `/mnt` from the host\n\nAssuming we're on a host with a private IP of 10.0.1.1 and the IP of docker bridge docker0 is 172.17.42.1 we can start the first host agent:\n\n\t$ docker run -d -h node1 -v /mnt:/data \\\n\t\t-p 10.0.1.1:8300:8300 \\\n\t\t-p 10.0.1.1:8301:8301 \\\n\t\t-p 10.0.1.1:8301:8301/udp \\\n\t\t-p 10.0.1.1:8302:8302 \\\n\t\t-p 10.0.1.1:8302:8302/udp \\\n\t\t-p 10.0.1.1:8400:8400 \\\n\t\t-p 10.0.1.1:8500:8500 \\\n\t\t-p 172.17.42.1:53:53/udp \\\n\t\tprogrium/consul -server -advertise 10.0.1.1 -bootstrap-expect 3\n\nOn the second host, we'd run the same thing, but passing a `-join` to the first node's IP. Let's say the private IP for this host is 10.0.1.2:\n\n\t$ docker run -d -h node2 -v /mnt:/data \\\n\t\t-p 10.0.1.2:8300:8300 \\\n\t\t-p 10.0.1.2:8301:8301 \\\n\t\t-p 10.0.1.2:8301:8301/udp \\\n\t\t-p 10.0.1.2:8302:8302 \\\n\t\t-p 10.0.1.2:8302:8302/udp \\\n\t\t-p 10.0.1.2:8400:8400 \\\n\t\t-p 10.0.1.2:8500:8500 \\\n\t\t-p 172.17.42.1:53:53/udp \\\n\t\tprogrium/consul -server -advertise 10.0.1.2 -join 10.0.1.1\n\nAnd the third host with an IP of 10.0.1.3:\n\n\t$ docker run -d -h node3 -v /mnt:/data \\\n\t\t-p 10.0.1.3:8300:8300 \\\n\t\t-p 10.0.1.3:8301:8301 \\\n\t\t-p 10.0.1.3:8301:8301/udp \\\n\t\t-p 10.0.1.3:8302:8302 \\\n\t\t-p 10.0.1.3:8302:8302/udp \\\n\t\t-p 10.0.1.3:8400:8400 \\\n\t\t-p 10.0.1.3:8500:8500 \\\n\t\t-p 172.17.42.1:53:53/udp \\\n\t\tprogrium/consul -server -advertise 10.0.1.3 -join 10.0.1.1\n\nThat's it! Once this last node connects, it will bootstrap into a cluster. You now have a working cluster running in production on a private network.\n\n## Special Features\n\n#### Runner command\n\nSince the `docker run` command to start in production is so long, a command is available to generate this for you. Running with `cmd:run [::[::client]] [docker-run-args...]` will output an opinionated, but customizable `docker run` command you can run in a subshell. For example:\n\n\t$ docker run --rm progrium/consul cmd:run 10.0.1.1 -d\n\nOutputs:\n\n\teval docker run --name consul -h $HOSTNAME \t\\\n\t\t-p 10.0.1.1:8300:8300 \\\n\t\t-p 10.0.1.1:8301:8301 \\\n\t\t-p 10.0.1.1:8301:8301/udp \\\n\t\t-p 10.0.1.1:8302:8302 \\\n\t\t-p 10.0.1.1:8302:8302/udp \\\n\t\t-p 10.0.1.1:8400:8400 \\\n\t\t-p 10.0.1.1:8500:8500 \\\n\t\t-p 172.17.42.1:53:53/udp \\\n\t\t-d \t\\\n\t\tprogrium/consul -server -advertise 10.0.1.1 -bootstrap-expect 3\n\nBy design, it will set the hostname of the container to your host hostname, it will name the container `consul` (though this can be overridden), it will bind port 53 to the Docker bridge, and the rest of the ports on the advertise IP. If no join IP is provided, it runs in `-bootstrap-expect` mode with a default of 3 expected peers. Here is another example, specifying a join IP and setting more docker run arguments:\n\n\t$ docker run --rm progrium/consul cmd:run 10.0.1.1::10.0.1.2 -d -v /mnt:/data\n\nOutputs:\n\n\teval docker run --name consul -h $HOSTNAME \t\\\n\t\t-p 10.0.1.1:8300:8300 \\\n\t\t-p 10.0.1.1:8301:8301 \\\n\t\t-p 10.0.1.1:8301:8301/udp \\\n\t\t-p 10.0.1.1:8302:8302 \\\n\t\t-p 10.0.1.1:8302:8302/udp \\\n\t\t-p 10.0.1.1:8400:8400 \\\n\t\t-p 10.0.1.1:8500:8500 \\\n\t\t-p 172.17.42.1:53:53/udp \\\n\t\t-d -v /mnt:/data \\\n\t\tprogrium/consul -server -advertise 10.0.1.1 -join 10.0.1.2\n\nYou may notice it lets you only run with bootstrap-expect or join, not both. Using `cmd:run` assumes you will be bootstrapping with the first node and expecting 3 nodes. You can change the expected peers before bootstrap by setting the `EXPECT` environment variable.\n\nTo use this convenience, you simply wrap the `cmd:run` output in a subshell. Run this to see it work:\n\n\t$ $(docker run --rm progrium/consul cmd:run 127.0.0.1 -it)\n\n##### Client flag\n\nClient nodes allow you to keep growing your cluster without impacting the performance of the underlying gossip protocol (they proxy requests to one of the server nodes and so are stateless).\n\nTo boot a client node using the runner command, append the string `::client` onto the `::` argument. For example:\n\n\t$ docker run --rm progrium/consul cmd:run 10.0.1.4::10.0.1.2::client -d\n\nWould create the same output as above but without the `-server` consul argument.\n\n#### Health checking with Docker\n\nConsul lets you specify a shell script to run for health checks, similar to Nagios. As a container, those scripts run inside this container environment which is a minimal Busybox environment with bash and curl. For some, this is fairly limiting, so I've added some built-in convenience scripts to properly do health checking in a Docker system. \n\nThese all require you to mount the host's Docker socket to `/var/run/docker.sock` when you run the Consul container.\n\n##### Using check-http\n\n\tcheck-http [curl-args...]\n\nThis utility performs `curl` based HTTP health checking given a container ID or name, an internal port (what the service is actually listening on inside the container) and a path. You can optionally provide extra arguments to `curl`. \n\nThe HTTP request is done in a separate ephemeral container that is attached to the target container's network namespace. The utility automatically determines the internal Docker IP to run the request against. A successful request will output the response headers into Consul. An unsuccessful request will output the reason the request failed and set the check to critical. By default, `curl` runs with `--retry 2` to cover local transient errors. \n\n##### Using check-cmd\n\n\tcheck-cmd \n\nThis utility performs the specified command in a separate ephemeral container based on the target container's image that is attached to that container's network namespace. Very often, this is expected to be a health check script, but can be anything that can be run as a command on this container image. For convenience, an environment variable `SERVICE_ADDR` is set with the internal Docker IP and port specified here. \n\n##### Using docker\n\nThe above health check utilities require the Docker binary, so it's already built-in to the container. If neither of the above fit your needs, and the container environment is too limiting, you can perform Docker operations directly to perform any containerized health check.\n\n#### DNS\n\nThis container was designed assuming you'll be using it for DNS on your other containers. So it listens on port 53 inside the container to be more compatible and accessible via linking. It also has DNS recursive queries enabled, using the Google 8.8.8.8 nameserver.\n\nWhen running with `cmd:run`, it publishes the DNS port on the Docker bridge. You can use this with the `--dns` flag in `docker run`, or better yet, use it with the Docker daemon options. Here is a command you can run on Ubuntu systems that will tell Docker to use the bridge IP for DNS, otherwise use Google DNS, and use `service.consul` as the search domain. \n\n\t$ echo \"DOCKER_OPTS='--dns 172.17.42.1 --dns 8.8.8.8 --dns-search service.consul'\" >> /etc/default/docker\n\nIf you're using [boot2docker](http://boot2docker.io/) on OS/X, rather than an Ubuntu host, it has a Tiny Core Linux VM running the docker containers. Use this command to set the extra Docker daemon options (as of boot2docker v1.3.1), which also uses the first DNS name server that your OS/X machine uses for name resolution outside of the boot2docker world.\n\n\t$ boot2docker ssh sudo \"ash -c \\\"echo EXTRA_ARGS=\\'--dns 172.17.42.1 --dns $(scutil --dns | awk -F ': ' '/nameserver/{print $2}' | head -1) --dns-search service.consul\\' > /var/lib/boot2docker/profile\\\"\"\n\nWith those extra options in place, within a Docker container, you have the appropriate entries automatically set in the `/etc/resolv.conf` file. To test it out, start a Docker container that has the `dig` utility installed (this example uses [aanand/docker-dnsutils](https://registry.hub.docker.com/u/aanand/docker-dnsutils/) which is the Ubuntu image with dnsutils installed).\n\n\t$ docker run --rm aanand/docker-dnsutils dig -t SRV consul +search\n\n#### Runtime Configuration\n\nAlthough you can extend this image to add configuration files to define services and checks, this container was designed for environments where services and checks can be configured at runtime via the HTTP API. \n\nIt's recommended you keep your check logic simple, such as using inline `curl` or `ping` commands. Otherwise, keep in mind the default shell is Bash, but you're running in Busybox.\n\nIf you absolutely need to customize startup configuration, you can extend this image by making a new Dockerfile based on this one and having a `config` directory containing config JSON files. They will be added to the image you build via ONBUILD hooks. You can also add packages with `opkg`. See [docs on the Busybox image](https://github.com/progrium/busybox) for more info.\n\n## Issue with quickly restarting a node using the same IP\n\nWhen testing a cluster scenario, you may kill a container and restart it again on the same host and see that it has trouble re-joining the cluster.\n\nThere is an issue when you restart a node as a new container with the same published ports that will cause heartbeats to fail and the node will flap. This is an ARP table caching problem. If you wait about 3 minutes before starting again, it should work fine. You can also manually reset the cache.\n\n## Sponsor\n\nThis project was made possible thanks to [DigitalOcean](http://digitalocean.com).\n\n## License\n\nBSD\n","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":21,"_83":11,"_84":11},"read","write","admin","user","storage_size",415444233,"orgData","recentTags",[91,129],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_50":118,"_119":94,"_120":33,"_121":56,"_57":122,"_123":124,"_125":109,"_126":118,"_127":65,"_128":21},"content_type","creator",956709,"full_size",31817108,"id",3769796,"images",[101],{"_102":103,"_104":105,"_106":107,"_108":109,"_110":111,"_112":113,"_114":107,"_115":-5,"_116":96,"_63":65,"_117":-5},"architecture","amd64","digest","sha256:6f347f076e3d56d72a2a3ddc6dac6921813a8b21d045b7819552a7f4f0e422dc","features","","last_pulled","2026-10-05T11:28:46.262830987Z","last_pushed","2016-09-14T00:14:02Z","os","linux","os_features","os_version","size","variant","2016-09-14T00:14:01.109385Z","last_updater","last_updater_username","media_type","latest","repository",790523,"tag_last_pulled","tag_last_pushed","tag_status","v2",{"_92":44,"_93":94,"_95":130,"_97":131,"_99":132,"_50":137,"_119":94,"_120":33,"_121":56,"_57":138,"_123":124,"_125":135,"_126":137,"_127":65,"_128":21},31817050,3769791,[133],{"_102":103,"_104":134,"_106":107,"_108":135,"_110":136,"_112":113,"_114":107,"_115":-5,"_116":130,"_63":65,"_117":-5},"sha256:47e33fec7fcb227f582075214980b1ead38362479ccbca9ab7cb85bec5eabfbd","2026-10-05T11:29:57.774763201Z","2016-09-14T00:12:33Z","2016-09-14T00:12:32.584457Z","1.0","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":152,"_159":160,"_146":173,"_174":11},{"_40":153,"_42":154,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":155,"_57":35,"_32":33,"_58":59,"_60":-5,"_61":62,"_63":62,"_64":65,"_66":-5,"_67":68,"_69":70,"_71":11,"_72":33,"_73":156,"_79":21,"_80":158,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":157},[78],{"_82":21,"_83":11,"_84":11},"tags",{"_161":162,"_163":-5,"_164":-5,"_165":166},"count",2,"next","previous","results",[167,170],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":168,"_50":118,"_119":94,"_120":33,"_121":56,"_57":122,"_123":124,"_125":109,"_126":118,"_127":65,"_128":21},[169],{"_102":103,"_104":105,"_106":107,"_108":109,"_110":111,"_112":113,"_114":107,"_115":-5,"_116":96,"_63":65,"_117":-5},{"_92":44,"_93":94,"_95":130,"_97":131,"_99":171,"_50":137,"_119":94,"_120":33,"_121":56,"_57":138,"_123":124,"_125":135,"_126":137,"_127":65,"_128":21},[172],{"_102":103,"_104":134,"_106":107,"_108":135,"_110":136,"_112":113,"_114":107,"_115":-5,"_116":130,"_63":65,"_117":-5},[],"canDeleteTags","actionData","errors"]

civiclabs/consul

Tags for civiclabs/consul