Establishing a Dedicated Container Network

docker network create consul-net

Fetching the Consul Image

docker pull consul:latest

Initializing the Primary Server Node

docker run -d \
  --name=leader-node \
  --hostname=leader-node \
  --network=consul-net \
  consul:latest agent -server -bootstrap-expect=3 -datacenter=us-east-1

The -bootstrap-expect flag dictates the expected count of server participants within the datacenter. The cluster bootstrap process will stall until the specified number of servers are connected. This approach is strongly recommmended over the -bootstrap flag for production deployments.

Retrieving the Leader Node IP

LEADER_IP="$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' leader-node)"

This environment variable captures the internal IP address of the initial server, facilitating the connection of subsequent nodes.

Provisioning Additional Server Nodes

docker run -d \
  --name=replica-node-1 \
  --hostname=replica-node-1 \
  --network=consul-net \
  consul:latest agent -server -join=${LEADER_IP} -datacenter=us-east-1

docker run -d \
  --name=replica-node-2 \
  --hostname=replica-node-2 \
  --network=consul-net \
  consul:latest agent -server -join=${LEADER_IP} -datacenter=us-east-1

Omitting the -server flag provisions a client node instead. Flags accept values separated by either a space or an equals sign (e.g., -datacenter=us-east-1 vs -datacenter us-east-1).

Deploying a Client Node with Web Interface

docker run -d \
  -p 8500:8500 \
  -p 8600:8600/udp \
  --name=client-ui \
  --hostname=client-ui \
  --network=consul-net \
  consul:latest agent -ui -client=0.0.0.0 -join=${LEADER_IP} -datacenter=us-east-1

The -ui parameter activates the Consul web dashboard, accessible on port 8500. By default, the client agent binds to localhost (127.0.0.1); setting -client=0.0.0.0 exposes the HTTP/DNS interfaces to external traffic outside the conatiner.

Key Agent Configuration Flags

• -advertise: The address advertised to other cluster members. Defaults to the bind address. Essential if the bind address is not routable.
• -bootstrap: Permits a single server to elect itself as the Raft leader. Only one server per datacenter should use this, and it is generally discouraged for multi-node clusters.
• -bootstrap-expect: The number of expected servers required before bootstrapping the cluster. Cannot be used in conjunction with -bootstrap.
• -bind: The internal address used for cluster communication. Must be reachable by all nodes. Supports both TCP and UDP protocols.
• -client: The bind address for HTTP, DNS, and RPC client interfaces. Defaults to 127.0.0.1 (loopback only). Set to 0.0.0.0 for external access.
• -config-file: Specifies an exact configuration file to load.
• -config-dir: A directory from which all . files are loaded and merged.
• -data-dir: A persistent data directory for the agent's state. Required for all agents and must survive reboots.
• -dc: Defines the datacenter name for the agent. Defaults to dc1.
• -encrypt: Provides a secret key for encrypted gossip communication. Generated via consul keygen. Must be identical across all nodes in the cluster.
• -http-port: The port for the HTTP API. Defaults to 8500.
• -join: The IP address of an existing agent to connect to upon startup. Can be specified multiple times. The agent fails if it cannot join any specified address.
• -retry-join: Similar to -join, but continues attempting to connect on failure.
• -retry-interval: The duration between join retry attempts. Defaults to 30 seconds.
• -retry-max: The maximum number of join retry attempts. Defaults to 0 (infinite).
• -log-level: Verbosity of agent logs. Valid options include trace, debug, info, warn, and err. Defaults to info.
• -node: The unique identifier for the node within the cluster. Defaults to the machine's hostname.
• -pid-file: File path to store the agent's PID, useful for sending SIGINT/SIGHUP signals.
• -protocol: The Consul communication protocol version.
• -rejoin: Forces the agent to attempt rejoining the cluster upon restart, ignoring previous graceful leaves.
• -server: Switches the agent into server mode. Uses the Raft consensus algorithm. A cluster requires at least one server, with a recommended maximum of five per datacenter.
• -syslog: Forwards logs to the system logger. Available on Linux and macOS.
• -ui-dir: Path to the directory containing the Web UI assets. Requires a readable directory.