containers/bitnami/consul

Bitnami Secure Image for HashiCorp Consul

HashiCorp Consul is a tool for discovering and configuring services in your infrastructure.

Overview of HashiCorp Consul Trademarks: This software listing is packaged by Bitnami. The respective trademarks mentioned in the offering are owned by the respective companies, and use of them does not imply any affiliation or endorsement.

TL;DR

docker run --name consul bitnami/consul:latest

You can find the available configuration options in the Environment Variables section.

Why use Bitnami Secure Images?

Those are hardened, minimal CVE images built and maintained by Bitnami. Bitnami Secure Images are based on the cloud-optimized, security-hardened enterprise OS Photon Linux. Why choose BSI images?

• Hardened secure images of popular open source software with Near-Zero Vulnerabilities
• Vulnerability Triage & Prioritization with VEX Statements, KEV and EPSS Scores
• Compliance focus with FIPS, STIG, and air-gap options, including secure bill of materials (SBOM)
• Software supply chain provenance attestation through in-toto
• First class support for the internet’s favorite Helm charts

Each image comes with valuable security metadata. You can view the metadata in our public catalog here. Note: Some data is only available with commercial subscriptions to BSI.

If you are looking for our previous generation of images based on Debian Linux, please see the Bitnami Legacy registry.

How to deploy HashiCorp Consul in Kubernetes?

Deploying Bitnami applications as Helm Charts is the easiest way to get started with our applications on Kubernetes. Read more about the installation in the Bitnami HashiCorp Consul Chart GitHub repository.

Why use a non-root container?

Non-root container images add an extra layer of security and are generally recommended for production environments. However, because they run as a non-root user, privileged tasks are typically off-limits. Learn more about non-root containers in our docs.

Supported tags and respective Dockerfile links

Learn more about the Bitnami tagging policy and the difference between rolling tags and immutable tags in our documentation page.

Get this image

The recommended way to get the Bitnami HashiCorp Consul Docker Image is to pull the prebuilt image from the Docker Hub Registry.

docker pull bitnami/consul:latest

To use a specific version, you can pull a versioned tag. You can view the list of available versions in the Docker Hub Registry.

docker pull bitnami/consul:[TAG]

If you wish, you can also build the image yourself by cloning the repository, changing to the directory containing the Dockerfile and executing the docker build command. Remember to replace the APP, VERSION and OPERATING-SYSTEM path placeholders in the example command below with the correct values.

git clone https://github.com/bitnami/containers.git
cd bitnami/APP/VERSION/OPERATING-SYSTEM
docker build -t bitnami/APP:latest .

Using docker-compose.yaml

Please be aware this file has not undergone internal testing. Consequently, we advise its use exclusively for development or testing purposes. For production-ready deployments, we highly recommend utilizing its associated Bitnami Helm chart.

Persisting your application

If you remove the container all your data and configurations will be lost, and the next time you run the image the database will be reinitialized. To avoid this loss of data, you should mount a volume that will persist even after the container is removed.

For persistence you should mount a volume at the /bitnami path. The above examples define a docker volume namely consul_data. The HashiCorp Consul application state will persist as long as this volume is not removed.

To avoid inadvertent removal of this volume you can mount host directories as data volumes. Alternatively you can make use of volume plugins to host the volume data.

Note

As this is a non-root container, the mounted files and directories must have the proper permissions for the UID 1001.

Connecting to other containers

Using Docker container networking, a different server running inside a container can easily be accessed by your application containers and vice-versa.

Containers attached to the same network can communicate with each other using the container name as the hostname.

Configuration

The following section describes the supported environment variables

Environment variables

The following tables list the main variables you can set.

Customizable environment variables

Name	Description	Default Value
CONSUL_RPC_PORT_NUMBER	Consul RPC port number.	8300
CONSUL_HTTP_PORT_NUMBER	Consul HTTP port number.	8500
CONSUL_HTTPS_PORT_NUMBER	Consul HTTPS port number.	-1
CONSUL_DNS_PORT_NUMBER	Consul DNS port number.	8600
CONSUL_AGENT_MODE	Consul agent mode.	server
CONSUL_DISABLE_KEYRING_FILE	Disable keyring file in Consul.	false
CONSUL_SERF_LAN_ADDRESS	LAN address for Serf daemon.	0.0.0.0
CONSUL_SERF_LAN_PORT_NUMBER	LAN port for Serf daemon.	8301
CONSUL_CLIENT_LAN_ADDRESS	LAN address for Consul clients.	0.0.0.0
CONSUL_RETRY_JOIN_ADDRESS	Consul node retry join address.	127.0.0.1
CONSUL_RETRY_JOIN_WAN_ADDRESS	Consul retry join WAN address.	127.0.0.1
CONSUL_BIND_INTERFACE	Consul bind interface.	nil
CONSUL_BIND_ADDR	Consul bind address.	nil
CONSUL_ENABLE_UI	Enable User Interface in Consul.	true
CONSUL_BOOTSTRAP_EXPECT	Expect bootstrap in Consul.	1
CONSUL_RAFT_MULTIPLIER	Consul Raft multiplier.	1
CONSUL_LOCAL_CONFIG	Consul local configuration.	nil
CONSUL_GOSSIP_ENCRYPTION	Use gossip encryption in Consul.	no
CONSUL_GOSSIP_ENCRYPTION_KEY	Base64-encoded Consul gossip private symmetric key.	nil
CONSUL_DATACENTER	Consul datacenter name.	dc1
CONSUL_DOMAIN	Consul domain.	consul
CONSUL_NODE_NAME	Consul domain name.	nil
CONSUL_DISABLE_HOST_NODE_ID	Disable host node ID.	true

Read-only environment variables

Name	Description	Value
CONSUL_BASE_DIR	Consul installation directory.	${BITNAMI_ROOT_DIR}/consul
CONSUL_CONF_DIR	Consul configuration directory.	${CONSUL_BASE_DIR}/conf
CONSUL_DEFAULT_CONF_DIR	Consul default configuration directory.	${CONSUL_BASE_DIR}/conf.default
CONSUL_BIN_DIR	Consul binary directory.	${CONSUL_BASE_DIR}/bin
CONSUL_CONF_FILE	Consul configuration file.	${CONSUL_CONF_DIR}/consul.json
CONSUL_ENCRYPT_FILE	Consul encryption configuration file.	${CONSUL_CONF_DIR}/encrypt.json
CONSUL_LOCAL_FILE	Consul local configuration file.	${CONSUL_CONF_DIR}/local.json
CONSUL_LOG_DIR	Directory where Consul logs are stored.	${CONSUL_BASE_DIR}/logs
CONSUL_LOG_FILE	Consul log file.	${CONSUL_LOG_DIR}/consul.log
CONSUL_VOLUME_DIR	Consul persistence directory.	/bitnami/consul
CONSUL_DATA_DIR	Consul directory where data is stored.	${CONSUL_VOLUME_DIR}
CONSUL_SSL_DIR	Consul SSL directory.	${CONSUL_BASE_DIR}/certificates
CONSUL_TMP_DIR	Consul temporary directory.	${CONSUL_BASE_DIR}/tmp
CONSUL_PID_FILE	Path to the PID file for Consul.	${CONSUL_TMP_DIR}/consul.pid
CONSUL_TEMPLATES_DIR	Consul templates directory.	${CONSUL_BASE_DIR}/templates
CONSUL_CONFIG_TEMPLATE_FILE	Consul configuration template file.	${CONSUL_TEMPLATES_DIR}/consul.json.tpl
CONSUL_ENCRYPT_TEMPLATE_FILE	Consul encrypt configuration template file.	${CONSUL_TEMPLATES_DIR}/encrypt.json.tpl
CONSUL_LOCAL_TEMPLATE_FILE	Consul local configuration template file.	${CONSUL_TEMPLATES_DIR}/local.json.tpl
CONSUL_INITSCRIPTS_DIR	Consul directory for init scripts.	/docker-entrypoint-initdb.d
CONSUL_DAEMON_USER	Consul system user.	consul
CONSUL_DAEMON_GROUP	Consul system group.	consul

Using custom HashiCorp Consul configuration files

In order to load your own configuration files, you will have to make them available to the container. You can do it doing the following:

• Mounting a volume with your custom configuration
• Adding custom configuration via environment variable.

By default, the configuration of HashiCorp Consul is written to /opt/bitnami/consul/consul.json file.

Configuring environment variables

Configuration can be added by passing the configuration in JSON format via the environment variable CONSUL_LOCAL_CONFIG. Then consul will write a local.json file in the HashiCorp Consul configuration directory. HashiCorp Consul will load all files within the configuration directory in alphabetical order, so ones with starting with higher letters will prevail.

Mounting a volume

Check the [Persisting your data](# Persisting your application) section to add custom volumes to the HashiCorp Consul container

Configuring the Gossip encryption key

Specifies the secret key to use for encryption of HashiCorp Consul network traffic. This key must be 16-bytes that are Base64-encoded. The easiest way to create an encryption key is to use consul keygen

docker run --name consul bitnami/consul:latest consul keygen

This command will generate a keygen, that you can add to your Dockerfile, docker-compose or pass it via command line:

docker run -e CONSUL_GOSSIP_ENCRYPTION_KEY=YOUR_GENERATED_KEY --name consul bitnami/consul:latest

FIPS configuration in Bitnami Secure Images

The Bitnami HashiCorp Consul Docker image from the Bitnami Secure Images catalog includes extra features and settings to configure the container with FIPS capabilities. You can configure the next environment variables:

• OPENSSL_FIPS: whether OpenSSL runs in FIPS mode or not. yes (default), no.

Logging

The Bitnami consul Docker image sends the container logs to the stdout. To view the logs:

docker logs consul

or using Docker Compose:

docker-compose logs consul

You can configure the containers logging driver using the --log-driver option if you wish to consume the container logs differently. In the default configuration docker uses the json-file driver.

Notable Changes

Debian 1.6.1-r6 and Oracle 1.6.1-r7

Decrease the size of the container. The configuration logic is now based on Bash scripts in the rootfs/ folder. Also, some env var changes have been performed maintaining backward compatibility through aliases:

New value	Old value
CONSUL_ENABLE_UI	CONSUL_UI
CONSUL_AGENT_MODE	CONSUL_SERVER_MODE
CONSUL_RETRY_JOIN_ADDRESS	CONSUL_RETRY_JOIN

1.4.0-r16

• The Consul container has been migrated to a non-root user approach. Previously the container ran as the root user and the Consul daemon was started as the consul user. From now on, both the container and the Consul daemon run as user 1001. As a consequence, the data directory must be writable by that user. You can revert this behavior by changing USER 1001 to USER root in the Dockerfile.

License

Copyright © 2026 Broadcom. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.