{"id":16130088,"url":"https://github.com/dj-wasabi/consul","last_synced_at":"2026-04-01T22:05:29.641Z","repository":{"id":52849831,"uuid":"55994852","full_name":"dj-wasabi/consul","owner":"dj-wasabi","description":"Docker container Consul running on Alpine ","archived":false,"fork":false,"pushed_at":"2021-04-16T13:57:19.000Z","size":166,"stargazers_count":10,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-03-28T00:37:58.948Z","etag":null,"topics":["alpine","cluster","consul","consul-server","docker","hashicorp-consul"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/wdijkerman/consul/","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dj-wasabi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"dj-wasabi","patreon":"wernerdijkerman"}},"created_at":"2016-04-11T17:57:42.000Z","updated_at":"2022-07-22T03:48:44.000Z","dependencies_parsed_at":"2022-08-22T23:30:40.837Z","dependency_job_id":null,"html_url":"https://github.com/dj-wasabi/consul","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/dj-wasabi/consul","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj-wasabi%2Fconsul","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj-wasabi%2Fconsul/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj-wasabi%2Fconsul/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj-wasabi%2Fconsul/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dj-wasabi","download_url":"https://codeload.github.com/dj-wasabi/consul/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dj-wasabi%2Fconsul/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine","cluster","consul","consul-server","docker","hashicorp-consul"],"created_at":"2024-10-09T22:14:26.723Z","updated_at":"2026-04-01T22:05:29.613Z","avatar_url":"https://github.com/dj-wasabi.png","language":"Dockerfile","funding_links":["https://github.com/sponsors/dj-wasabi","https://patreon.com/wernerdijkerman"],"categories":[],"sub_categories":[],"readme":"# wdijkerman/consul\n\n\u003c!--TOC--\u003e\n\n- [wdijkerman/consul](#wdijkermanconsul)\n- [Introduction](#introduction)\n  - [Volumes](#volumes)\n  - [User](#user)\n  - [Python?](#python)\n- [Install the container](#install-the-container)\n- [Using the container](#using-the-container)\n  - [Single node (Cluster) server](#single-node-cluster-server)\n  - [Multi node cluster](#multi-node-cluster)\n  - [Agent](#agent)\n  - [docker-compose](#docker-compose)\n- [Configurations](#configurations)\n  - [Environment variables](#environment-variables)\n  - [Add commandline](#add-commandline)\n  - [Add configuration file](#add-configuration-file)\n- [Ports](#ports)\n- [how to's](#how-tos)\n- [License](#license)\n- [Issues](#issues)\n\n\u003c!--TOC--\u003e\n\n![Docker Stars](https://img.shields.io/docker/stars/wdijkerman/consul.svg) ![Docker Pulls](https://img.shields.io/docker/pulls/wdijkerman/consul.svg) [![](https://images.microbadger.com/badges/image/wdijkerman/consul.svg)](https://microbadger.com/images/wdijkerman/consul \"Get your own image badge on microbadger.com\") [![](https://images.microbadger.com/badges/version/wdijkerman/consul.svg)](https://microbadger.com/images/wdijkerman/consul \"Get your own version badge on microbadger.com\") [![Build Status](https://github.com/dj-wasabi/consul/workflows/CI/badge.svg)](https://github.com/dj-wasabi/consul/actions?query=workflow%3ACI)\n\n# Introduction\n\nThis is an Docker container for Consul running on Alpine. The container is small, a little bit more than 75MB in size.\n\nThe versions in this Docker container:\n\n* alpine: 3.13\n* consul: 1.9.4\n* python: 3.8.5\n\n## Volumes\nThe consul application is installed in the /bin directory in the container, so is the start script. There data from Consul is in the /consul directory:\n\n* /consul/config\n* /consul/data\n\n*/consul/config*\nThe location of the config.json file. This is also an volume, so this can be mounted on the host.\n\n*/consul/data*\nThe location where Consul will store all data. This is also an volume, so this can be mounted on the host.\n\n## User\n\nConsul is running as user consul. With the following capabilities (which are configured in this container)it should be no problem running Consul as non-root user:\n\n- cap_ipc_lock (Should not swap. Also `--cap-add IPC_LOCK` should be added to the command line when to start the Consul Server)\n- cap_net_bind_service (Can bind service \u003c1023 as non root user)\n\nThe UID used in this container is 1050. So make sure the id is already available on the host running the container when host mounts are used.\n\n## Python?\n\nPython is also installed in the container. Python is used for testing the container, which is done with the tool `testinfra`.\nYou can see in the `tests` directory a file named `test_consul.py` which will be executed.\n\n# Install the container\n\nJust run the following command to download the container:\n\n```bash\ndocker pull wdijkerman/consul\n```\n\n# Using the container\n\nThere are several ways to use this container.\n\n## Single node (Cluster) server\n\nThis example will boot an single node Consul server, without any agents.\n\nThe following json file needs to be stored somewhere:\n\n```json\n{\n\t\"data_dir\": \"/consul/data\",\n\t\"log_level\": \"INFO\",\n\t\"client_addr\": \"0.0.0.0\",\n\t\"ports\": {\n\t\t\"dns\": 53\n\t},\n\t\"ui\": true,\n\t\"server\": true,\n    \"bootstrap_expect\": 1,\n\t\"disable_update_check\": true\n}\n```\n\nThen you can use the following command to boot the Single node cluster:\n\n```bash\ndocker run  -p 8400:8400 -p 8500:8500 \\\n            -p 8600:53/udp -h server1 \\\n            -v path/to/file.json:/consul/config/my_config.json:ro \\\n            wdijkerman/consul\n```\n\n\n## Multi node cluster\n\nAccording to the official documentation of Consul bu Hashicorp, the best (or optimal) cluster size will be 3 or 5 nodes. The first node in the cluster is started differently than the others. The first node will be started like this:\n\n```bash\ndocker run  -p 8300-8302:8300-8302 \\\n            -p 8301-8302:8301-8302/udp \\\n            -p 8400:8400 -p 8500:8500 \\\n            -p 8600:53 -p 8600:53/udp \\\n            -v /data/consul/cluster:/consul/data \\\n            -v /data/consul/config:/consul/config \\\n            -h server1 wdijkerman/consul\n```\n\nAs you see, we started the Consul cluster with the `-bootstrap-expect 3` option. We let the Consul Cluster know that the size will be 3 `server` nodes. It doesn't matter how many agent nodes it use.\nWe have an local directory '/data/consul/cluster' that will be mounted in the container, so no Consul data is lost when the container is restarted. (Make sure the UID of the directories are set to 995)\n\nThe rest of the nodes are started with the `-join` command. We do need the ip for the first Consul server first.\n\n```bash\ndocker run  -p 8300-8302:8300-8302 \\\n            -p 8301-8302:8301-8302/udp \\\n            -p 8400:8400 -p 8500:8500 \\\n            -p 8600:53 -p 8600:53/udp \\\n            -v /data/consul/cluster:/consul/data \\\n            -v /data/consul/config:/consul/config \\\n            -h server[2-5] wdijkerman/consul\n```\n\nThe rest of the server will initially connect to the first booted server and will join the cluster. \n\n## Agent\n\nWhen we have an Consul cluster, we can add agents to the cluster. They will handle the requests from other docker services\n\n```bash\ndocker run  -p 8301-8302:8301-8302 \\\n            -p 8301-8302:8301-8302/udp \\\n            -p 8400:8400 -p 8500:8500 \\\n            -p 8600:53 -p 8600:53/udp \\\n            -h agent[1-??] wdijkerman/consul\n```\n\n## docker-compose\n\nA `docker-compose.yml` file is present in the root, that can be used for starting a basic single node Consul Server.\n\n```bash\ndocker-compose -f docker-compose.yml up consul\n```\n\n# Configurations\n\nThere are a lot of options to configure Consul. See this page for all options: https://www.consul.io/docs/agent/options.html\n\n## Environment variables\n\nYou can use the following environment variables for configuring Consul:\n\n* `CONSUL_INTERFACE_ADVERTISE`: When a network interface is configured, it will use that ip of the interface as advertise address. \n* `CONSUL_INTERFACE_BIND`: When a network interface is configured, it will use that ip of the interface as bind address.\n* `CONSUL_INTERFACE_CLIENT`: When a network interface is configured, it will use that ip of the interface as client address.\n\nExample:\n\n```bash\n-e CONSUL_INTERFACE_BIND=eth0\n```\n\n## Add commandline\n\nYou can add the options in the command line, see the following example:\n\n```bash\ndocker run  -p 8301-8302:8301-8302 \\\n            -p 8301-8302:8301-8302/udp \\\n            -p 8400:8400 -p 8500:8500 \\\n            -p 8600:53 -p 8600:53/udp \\\n            -h agent[1-??] wdijkerman/consul\n```\n\nIn the configuration you see above, we have added the `-advertise` configuration option.\n\n## Add configuration file\n\nYou can also add a json configuration file. Place the json file in the `/data/consul/config` directory (Or use the directory which you use for storing configuration).\n\n```\ncat /data/consul/config/datacenter.json\n{\n  \"datacenter\": \"nwg\"\n}\n```\n\nWhen Consul is restarted, you'll see that the datacenter is set to \"nwg\".\n\n```\n==\u003e Starting Consul agent...\n==\u003e Starting Consul agent RPC...\n==\u003e Consul agent running!\n           Version: 'v0.7.2'\n         Node name: 'server1'\n        Datacenter: 'nwg'\n            Server: true (bootstrap: true)\n       Client Addr: 0.0.0.0 (HTTP: 8500, HTTPS: -1, DNS: 53, RPC: 8400)\n      Cluster Addr: 172.17.0.2 (LAN: 8301, WAN: 8302)\n    Gossip encrypt: false, RPC-TLS: false, TLS-Incoming: false\n             Atlas: \u003cdisabled\u003e\n```\n\n# Ports\n\nConsul requires up to 5 different ports to work properly, some on TCP, UDP, or both protocols. Below we document the requirements for each port.\n\n* Server RPC (Default 8300). This is used by servers to handle incoming requests from other agents. TCP only.\n* Serf LAN (Default 8301). This is used to handle gossip in the LAN. Required by all agents. TCP and UDP.\n* Serf WAN (Default 8302). This is used by servers to gossip over the WAN to other servers. TCP and UDP.\n* CLI RPC (Default 8400). This is used by all agents to handle RPC from the CLI. TCP only.\n* HTTP API (Default 8500). This is used by clients to talk to the HTTP API. TCP only.\n* gRPC (Default 8502). This is used for to expose Envoy xDS API to Envoy proxies\n* DNS Interface (Default 8600). Used to resolve DNS queries. TCP and UDP.\n\n# how to's\n\n[Setting up a secure Consul cluster](https://werner-dijkerman.nl/2017/01/09/setting-up-a-secure-consul-cluster-with-docker/)\n[Configuring Access Control Lists](https://werner-dijkerman.nl/2017/01/11/configuring-access-control-lists-in-consul/)\n\n# License\n\nThe MIT License (MIT)\n\nSee file: License\n\n# Issues\n\nPlease report issues at https://github.com/dj-wasabi/consul/issues\n\nPull Requests are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdj-wasabi%2Fconsul","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdj-wasabi%2Fconsul","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdj-wasabi%2Fconsul/lists"}