Getting Started with HashiCorp Consul: Install, Configure, and Run Your First Cluster

What Is HashiCorp Consul?

HashiCorp Consul is an open-source tool that provides service discovery, health checking, key/value storage, and a service mesh capability for distributed systems. Whether you're running a handful of microservices or a sprawling multi-datacenter architecture, Consul gives you a single control plane to track what's running, where it is, and whether it's healthy.

Prerequisites

• A Linux, macOS, or Windows machine (or VM)
• Basic comfort with the command line
• At least 512 MB of RAM for a development node

Step 1: Install Consul

Consul is distributed as a single binary. The easiest way to install it is via HashiCorp's official package repository or by downloading a release directly from developer.hashicorp.com.

On Ubuntu / Debian

wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install consul

On macOS (Homebrew)

brew tap hashicorp/tap
brew install hashicorp/tap/consul

Verify the installation by running consul version. You should see the version number printed to your terminal.

Step 2: Start a Development Agent

Consul ships with a convenient development mode that runs a single-node cluster entirely in memory — perfect for learning and local testing. Start it with:

consul agent -dev

You'll see log output indicating the agent has started, elected itself as a leader (since it's alone), and is ready to accept connections. The built-in UI is available at http://localhost:8500.

Step 3: Explore the CLI and UI

With your dev agent running, open a second terminal and try a few commands:

• consul members — lists all nodes in the cluster
• consul catalog services — shows registered services (you'll see "consul" itself)
• consul kv put myapp/config/loglevel debug — writes a key/value pair
• consul kv get myapp/config/loglevel — reads it back

Step 4: Register Your First Service

Create a service definition file at /etc/consul.d/web.json:

{
  "service": {
    "name": "web",
    "port": 80,
    "check": {
      "http": "http://localhost:80/health",
      "interval": "10s"
    }
  }
}

Then reload Consul with consul reload. Your service will now appear in the catalog and begin health-check polling.

Understanding the Agent Modes

Mode	Role	Persistent State?
Server	Participates in Raft consensus, stores all state	Yes
Client	Forwards requests to servers, runs health checks	No
Dev	Single-node server, in-memory only	No

Next Steps

Now that you have Consul running locally, the natural next steps are:

1. Bootstrap a three-node server cluster for high availability
2. Configure gossip encryption and TLS for production use
3. Explore Consul's DNS interface for transparent service discovery

Consul's power grows dramatically once you move beyond a single agent. Start with the concepts here, then build toward a production-ready cluster with proper ACLs and persistent storage.