Skip to main content
You have four existing machines and one downloaded file. A small amount of configuration turns those machines into a Nomad cluster. This guide walks through the required config files and verification steps so you can avoid the most common setup problems — nearly all cluster issues come from one misconfigured value rather than complex failures. Maya’s example cluster uses two roles:
  • Servers — hold cluster state and make scheduling decisions; they do not run user workloads.
  • Clients — run containers and tasks; they report availability to the servers.
Separating servers and clients keeps cluster state small and predictable: servers can be small, inexpensive VMs that never compete with your applications for CPU or memory.
A presentation slide titled "Two Kinds of Machine" showing icons for servers, storage, and Docker-style clients. The slide reads "Servers decide. Clients run." and depicts four labeled box instances at the bottom.

​
Server configuration

Start by provisioning three small server machines. Create server.hcl on each server and set the persistent data directory, the bind address, and the server block that enables server mode and declares the expected number of servers.
  • data_dir — where Nomad writes persistent state on disk. Use a stable path outside temp folders so state survives reboots and cleanup.
  • bind_addr = "0.0.0.0" — listen on all network interfaces (not just localhost).
  • bootstrap_expect — how many server nodes should form the cluster before electing a leader.
Set bootstrap_expect to the total number of server nodes you intend to run. For production use an odd number (3 or 5) so servers can form a quorum if one node fails. If bootstrap_expect = 3, Nomad will wait until it can see 3 servers before electing a leader — starting fewer than this will leave the cluster inactive.
Why choose three servers? Server leader election uses majority votes. With 3 servers you can lose one and still achieve a majority (2 of 3). With 4 servers you still need 3 to form a majority, so the fourth node increases cost without improving single-failure tolerance. In general: 3 tolerates one failure, 5 tolerates two; higher counts add latency and cost.
A presentation slide titled "Why the Number Is Odd" showing a balance scale and server icons with the caption "Three survives one failure." Below are four labeled boxes (box-1 to box-4) with server and Docker whale icons illustrating redundancy.

​
Client configuration

On your application machines, enable client mode. Create client.hcl and add a server_join block so clients will continuously retry connecting to the server addresses. This removes strict boot ordering: clients will keep trying until the servers are reachable.
  • retry_join should list server IPs or hostnames. Clients will retry these addresses until they join a server.

​
Important network ports

Ensure the machines can reach each other on the Nomad ports below. A misconfigured firewall blocking these ports (especially server-to-server gossip) is a common cause of failed clusters.
Open ports 4646, 4647, and 4648 as required. Clients need 4646 and 4647 to talk to servers; they do not need 4648. Blocked or filtered 4647/4648 between servers is the most frequent networking cause of cluster formation failures.
A slide titled "Three Ports" listing ports 4646 (HTTP and UI), 4647 (clients to servers) and 4648 (gossip) with corresponding icons. Below are four server/box illustrations with Docker whale icons and the note "Boot order stops mattering."

​
Start the agents and verify the cluster

Start the Nomad agent on each machine using the appropriate config file. Example commands to check cluster status:
  • nomad server members — shows known servers and which one is leader.
  • nomad node status — lists registered client nodes and their readiness.
When every client reports ready, your cluster can accept jobs. Note that no physical changes were made to Maya’s machines — the cluster exists because Nomad servers now hold state and schedule work across the client machines.

​
Next step: running workloads

A newly formed cluster is empty: it knows about machines but has nothing to run. Submit a Nomad job specification (.nomad HCL file or equivalent) to tell Nomad what to schedule, how many instances to run, which resources to reserve, and which containers or tasks to launch.

​
Quick reference

Watch Video

Practice Lab