---
layout: docs
page_title: Deploy Consul server agent on Docker
description: >-
   Learn how to deploy a Consul server agent on a Docker container.
---

# Deploy Consul server agent on Docker

This topic provides an overview for deploying a Consul server when running Consul on Docker containers.

## Deploy and run a Consul server

You can start a Consul server container and configure the Consul agent from the command line. 

The following example starts the Docker container and includes a `consul agent -server` sub-command to configure the Consul server agent and enable the UI.

```shell-session
$ docker run --name=consul-server -d -p 8500:8500 -p 8600:8600/udp hashicorp/consul consul agent -server -ui -node=server-1 -bootstrap-expect=1 -client=0.0.0.0 -data-dir=/consul/data
```

Since you started the container in detached mode, `-d`, the process will run in the background. You also set port mapping to your local machine as well as binding the client interface of your agent to `0.0.0.0`. This configuration allows you to work directly with the Consul datacenter from your local machine and access Consul's UI and DNS over `localhost`. Finally, you are using Docker's default bridge network.

Note, the Consul Docker image sets up the Consul configuration directory at `/consul/config` by default. The agent will load any configuration files placed in that directory.

The configuration directory is not exposed as a volume and does not persist data. Consul uses it only during startup and does not store any state there.

 You can also submit a Consul configuration in JSON format with the environment variable `CONSUL_LOCAL_CONFIG`. This approach does not require mounting volumes or copying files to the container. For more information, refer to the [Consul on Docker documentation](/consul/docs/docker#consul-agent).

### Discover the server IP address

To find the IP address of the Consul server, execute the `consul members` command inside of the `consul-server` container.

```shell-session
$  docker exec consul-server consul members
Node      Address          Status  Type    Build   Protocol  DC   Partition  Segment
server-1  172.17.0.2:8301  alive   server  1.21.2  2         dc1  default    <all>
```

## Multi-node Consul cluster

You can start a Consul cluster with multiple server containers that mimick more closely a production environment. The following example uses a Docker compose file to start three Consul server containers.

<CodeBlockConfig filename="consul-cluster.yml">

```yaml
version: '3.7'
services:
  consul-server1:
    image: hashicorp/consul:1.21.3
    container_name: consul-server1
    restart: always
    networks:
      - consul
    ports:
      - "8500:8500"
      - "8600:8600/tcp"
      - "8600:8600/udp"
    command: "agent -server -ui -data-dir='/consul/data' -node=consul-server1 -retry-join=consul-server2 -bootstrap-expect=3"
  consul-server2:
    image: hashicorp/consul:1.21.3
    container_name: consul-server2
    restart: always
    networks:
      - consul
    command: "agent -server -ui -data-dir='/consul/data' -node=consul-server2 -retry-join=consul-server1 -bootstrap-expect=3"
  consul-server3:
    image: hashicorp/consul:1.21.3
    container_name: consul-server3
    restart: always
    networks:
      - consul
    command: "agent -server -ui -data-dir='/consul/data' -node=consul-server3 -retry-join=consul-server1 -bootstrap-expect=3"
networks:
  consul:
    driver: bridge
```

</CodeBlockConfig>

You can start the cluster with the following command:

```shell-session
$ docker-compose -f consul-cluster.yml up -d
[+] Running 4/4
 ✔ Network docker_consul     Created                                0.0s
 ✔ Container consul-server3  Started                                0.2s
 ✔ Container consul-server1  Started                                0.2s
 ✔ Container consul-server2  Started                                0.2s
```

This command starts the three Consul server containers in detached mode. Each server is configured to expect three servers in the cluster, which is specified by the `-bootstrap-expect=3` flag.

You can verify the status of the cluster by executing the `consul members` command inside any of the server containers:

```shell-session
$ docker exec consul-server1 consul members
Node            Address          Status  Type    Build   Protocol  DC   Partition  Segment
consul-server1  172.19.0.2:8301  alive   server  1.21.3  2         dc1  default    <all>
consul-server2  172.19.0.4:8301  alive   server  1.21.3  2         dc1  default    <all>
consul-server3  172.19.0.3:8301  alive   server  1.21.3  2         dc1  default    <all>
```

You can also access the Consul UI by navigating to [http://localhost:8500](http://localhost:8500) in your web browser, because in the Docker compose file the port `8500` on you local machine is forwarded to the `consul-server1` container.
