Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Installing Consul and Running a Dev Agent

Install the Consul binary on Linux, macOS, Windows or Docker, start a single-node dev agent, check members and open the UI. Includes a port-conflict checker.

Consul ships as a single binary called consul. The same file is the server, the client agent and the command-line tool, which makes installing it pleasantly boring. In this lesson you install it, start a throwaway dev agent on your laptop, and learn the first commands for looking around.

Everything shown with $ is a command you run in your own terminal; the site cannot run Consul, so these blocks are read-only. The two runnable programs are stand-ins that practice reading output and planning ports.

Installing the binary

Pick whichever route fits your system. HashiCorp publishes a signed zip for every platform, plus package repositories.

Terminal
# macOS (Homebrew)
$ brew tap hashicorp/tap
$ brew install hashicorp/tap/consul

# Windows (Chocolatey)
> choco install consul

# Debian/Ubuntu: add HashiCorp's apt repository first, then
$ sudo apt update && sudo apt install consul

# Any platform: download the zip from releases.hashicorp.com/consul,
# unzip it and put the `consul` file on your PATH.

# Containers
$ docker run --rm -p 8500:8500 hashicorp/consul agent -dev -client=0.0.0.0

Confirm it works:

Terminal
$ consul version

The first line prints Consul v1.x.y plus the build date and protocol range. Always check this before following any tutorial, because flags and defaults evolve.

Download only from releases.hashicorp.com, the official package repositories, or the official Docker image, and verify the SHA-256 checksum or signature for manual downloads.

The dev agent

For learning, Consul has a one-line mode:

Terminal
$ consul agent -dev

-dev starts a single server that is its own cluster. It is configured for convenience:

  • everything lives in memory; stop the process and all data is gone;
  • it elects itself leader immediately (no peers needed);
  • ACLs are off, gossip encryption and TLS are off;
  • the HTTP API and UI listen on 127.0.0.1:8500, DNS on 127.0.0.1:8600.

Leave it running in one terminal; it streams log lines. Open a second terminal for the commands below.

Never use -dev in production. It has no persistence, no security and only one server, so one crash loses everything.

Looking around

Terminal
$ consul members          # who is in the gossip pool
$ consul catalog nodes    # nodes in the catalog
$ consul catalog services # service names (a fresh agent lists only "consul")
$ consul info             # agent and Raft statistics
$ consul operator raft list-peers   # Raft servers and who is the leader

consul members prints a table whose columns include Node, Address, Status, Type (server or client), Build, Protocol and DC. Status is alive, leaving, left or failed. A dev agent shows one row: your machine, type server, status alive.

Even an empty cluster has one service named consul, which represents the Consul servers themselves.

Open http://127.0.0.1:8500 in a browser for the web UI, which shows Services, Nodes, Key/Value and more. Stop the agent with Ctrl+C; Consul performs a graceful leave.

Reading members output

Operators often parse consul members in scripts. The stand-in below uses a made-up sample shaped like the real table (it is not captured from a real cluster) to count alive and failed members per datacenter.

Python Stand-in: parse a members-style table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Planning ports for several local agents

You can run more than one agent on a single machine for experiments, but each needs different ports. With flags such as -http-port, -dns-port, -serf-lan-port and -server-port you move each agent. The stand-in below checks a plan for collisions, which is the usual reason a second agent fails to start.

Python Stand-in: detect port collisions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Dev agent useful flags

Flag Effect
-client=0.0.0.0 Bind the HTTP and DNS interfaces on all addresses (needed inside containers)
-ui Serve the web UI (already on in dev mode)
-node=my-laptop Choose the node name
-datacenter=dc1 Name the datacenter (default is dc1)
-log-level=debug More logging while you learn
-config-dir=./conf.d Load service definitions and settings from files

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does consul agent -dev create?

    Dev mode is a self-contained, in-memory, single-server agent. It is not for production.
  2. 2. Which default address serves the Consul web UI and HTTP API?

    HTTP and UI use 8500. 8300 is server RPC and 8600 is DNS.
  3. 3. You stop a dev agent and start it again. What happened to the services you registered?

    Dev mode stores nothing on disk, so a restart starts empty.
  4. 4. A second local agent fails to start with an 'address already in use' error. What is the likely fix?

    Each agent needs its own ports when sharing one machine.

Summary

  • Consul is one binary: install it from official packages, the zip or the Docker image.
  • consul agent -dev starts an in-memory single-server cluster for learning only.
  • Use consul members, consul catalog nodes and consul catalog services to look around.
  • The UI and HTTP API are on port 8500, DNS on 8600.
  • Multiple local agents need distinct ports.

Next: The Consul CLI and HTTP API