HashiCorp Nomad

advanced

Simple and flexible workload orchestrator for containers and non-containerized apps.

Overview

HashiCorp Nomad is a simple and flexible workload orchestrator designed to schedule and manage containers, legacy applications, virtual machines, and other workloads across on-premises and cloud environments. Unlike complex orchestration platforms, Nomad focuses on simplicity with a single binary deployment while supporting diverse workload types including Docker containers, Java applications, and system processes. It provides native integration with other HashiCorp tools and offers powerful scheduling capabilities without the operational overhead of more complex systems. This deployment creates a complete Nomad cluster with three essential services: a Nomad server node that handles scheduling decisions and maintains cluster state, a Nomad client node that executes workloads and reports resource availability, and a Consul instance for service discovery and coordination. The server runs with bootstrap mode for single-node operation, while the client connects with privileged access to manage Docker containers and system resources. Consul provides the service mesh and key-value store capabilities that enhance Nomad's scheduling and service discovery features. This configuration is ideal for organizations wanting to explore container orchestration beyond Kubernetes, teams managing mixed workloads that include both containerized and traditional applications, and HashiCorp stack users seeking integrated tooling. The setup provides a production-like environment for testing Nomad's unique capabilities like batch job scheduling, multi-datacenter federation, and support for non-containerized workloads while maintaining the simplicity that makes Nomad attractive for smaller teams and specific use cases.

Key Features

Multi-workload scheduling supporting Docker containers, Java applications, and raw executables
Single binary architecture with minimal operational complexity compared to Kubernetes
Native Consul integration for service discovery and health checking
Batch job scheduling with automatic retry and constraint-based placement
Blue-green deployment support with built-in rolling update strategies
Privileged client access enabling GPU workloads and system-level task execution
Federation capabilities for multi-datacenter workload distribution
Built-in service discovery and load balancing through Consul integration

Common Use Cases

1Container orchestration for teams seeking simpler alternatives to Kubernetes
2Mixed environment management with both containerized and legacy applications
3Batch processing workflows requiring scheduled job execution and resource management
4Development and testing environments for HashiCorp stack integration
5Edge computing deployments where lightweight orchestration is preferred
6CI/CD pipeline execution with dynamic resource allocation
7Machine learning workloads requiring GPU scheduling and batch processing

Prerequisites

Docker Engine with privileged container support for client operations
Minimum 1GB RAM (512MB+ recommended per Nomad instance, 256MB+ for Consul)
Available ports 4646-4648 for Nomad and 8500 for Consul web interfaces
Basic understanding of job specification files and HCL configuration syntax
Knowledge of container networking concepts for service discovery setup
Familiarity with HashiCorp tools ecosystem for optimal configuration

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  nomad-server: 
3    image: hashicorp/nomad:latest
4    container_name: nomad-server
5    command: agent -server -bootstrap-expect=1 -bind=0.0.0.0
6    cap_add: 
7      - SYS_ADMIN
8    volumes: 
9      - ./nomad-server.hcl:/etc/nomad.d/nomad.hcl:ro
10      - nomad-server-data:/opt/nomad/data
11    ports: 
12      - "4646:4646"
13      - "4647:4647"
14      - "4648:4648"
15    networks: 
16      - nomad-network
17    restart: unless-stopped
18
19  nomad-client: 
20    image: hashicorp/nomad:latest
21    container_name: nomad-client
22    command: agent -client -servers=nomad-server:4647
23    privileged: true
24    cap_add: 
25      - SYS_ADMIN
26    volumes: 
27      - ./nomad-client.hcl:/etc/nomad.d/nomad.hcl:ro
28      - nomad-client-data:/opt/nomad/data
29      - /var/run/docker.sock:/var/run/docker.sock
30    depends_on: 
31      - nomad-server
32    networks: 
33      - nomad-network
34    restart: unless-stopped
35
36  consul: 
37    image: hashicorp/consul:latest
38    container_name: nomad-consul
39    command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
40    environment: 
41      - CONSUL_BIND_INTERFACE=eth0
42    volumes: 
43      - consul-data:/consul/data
44    ports: 
45      - "8500:8500"
46    networks: 
47      - nomad-network
48    restart: unless-stopped
49
50volumes: 
51  nomad-server-data: 
52  nomad-client-data: 
53  consul-data: 
54
55networks: 
56  nomad-network: 
57    driver: bridge

.env Template

.env

1# HashiCorp Nomad
2# Configure nomad-server.hcl and nomad-client.hcl

Usage Notes

1Nomad UI at http://localhost:4646
2Consul UI at http://localhost:8500
3Deploy jobs: nomad job run job.nomad
4Supports Docker, exec, raw_exec
5Integrates with Vault and Consul

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

nomad-server

nomad-server:
  image: hashicorp/nomad:latest
  container_name: nomad-server
  command: agent -server -bootstrap-expect=1 -bind=0.0.0.0
  cap_add:
    - SYS_ADMIN
  volumes:
    - ./nomad-server.hcl:/etc/nomad.d/nomad.hcl:ro
    - nomad-server-data:/opt/nomad/data
  ports:
    - "4646:4646"
    - "4647:4647"
    - "4648:4648"
  networks:
    - nomad-network
  restart: unless-stopped

nomad-client

nomad-client:
  image: hashicorp/nomad:latest
  container_name: nomad-client
  command: agent -client -servers=nomad-server:4647
  privileged: true
  cap_add:
    - SYS_ADMIN
  volumes:
    - ./nomad-client.hcl:/etc/nomad.d/nomad.hcl:ro
    - nomad-client-data:/opt/nomad/data
    - /var/run/docker.sock:/var/run/docker.sock
  depends_on:
    - nomad-server
  networks:
    - nomad-network
  restart: unless-stopped

consul

consul:
  image: hashicorp/consul:latest
  container_name: nomad-consul
  command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
  environment:
    - CONSUL_BIND_INTERFACE=eth0
  volumes:
    - consul-data:/consul/data
  ports:
    - "8500:8500"
  networks:
    - nomad-network
  restart: unless-stopped

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  nomad-server:
5    image: hashicorp/nomad:latest
6    container_name: nomad-server
7    command: agent -server -bootstrap-expect=1 -bind=0.0.0.0
8    cap_add:
9      - SYS_ADMIN
10    volumes:
11      - ./nomad-server.hcl:/etc/nomad.d/nomad.hcl:ro
12      - nomad-server-data:/opt/nomad/data
13    ports:
14      - "4646:4646"
15      - "4647:4647"
16      - "4648:4648"
17    networks:
18      - nomad-network
19    restart: unless-stopped
20
21  nomad-client:
22    image: hashicorp/nomad:latest
23    container_name: nomad-client
24    command: agent -client -servers=nomad-server:4647
25    privileged: true
26    cap_add:
27      - SYS_ADMIN
28    volumes:
29      - ./nomad-client.hcl:/etc/nomad.d/nomad.hcl:ro
30      - nomad-client-data:/opt/nomad/data
31      - /var/run/docker.sock:/var/run/docker.sock
32    depends_on:
33      - nomad-server
34    networks:
35      - nomad-network
36    restart: unless-stopped
37
38  consul:
39    image: hashicorp/consul:latest
40    container_name: nomad-consul
41    command: agent -server -bootstrap-expect=1 -ui -client=0.0.0.0
42    environment:
43      - CONSUL_BIND_INTERFACE=eth0
44    volumes:
45      - consul-data:/consul/data
46    ports:
47      - "8500:8500"
48    networks:
49      - nomad-network
50    restart: unless-stopped
51
52volumes:
53  nomad-server-data:
54  nomad-client-data:
55  consul-data:
56
57networks:
58  nomad-network:
59    driver: bridge
60EOF
61
62# 2. Create the .env file
63cat > .env << 'EOF'
64# HashiCorp Nomad
65# Configure nomad-server.hcl and nomad-client.hcl
66EOF
67
68# 3. Start the services
69docker compose up -d
70
71# 4. View logs
72docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/hashicorp-nomad/run | bash

Troubleshooting

Nomad client fails to connect: Verify nomad-server is fully started and port 4647 is accessible within the Docker network
Jobs fail with 'docker driver not found': Ensure nomad-client has privileged: true and access to /var/run/docker.sock
Consul UI shows no services: Check that Nomad agents are properly configured to register with Consul and network connectivity exists
Resource allocation errors: Verify nomad-client has sufficient CPU and memory resources available and SYS_ADMIN capability
Bootstrap failures on restart: Remove nomad-server-data volume to re-bootstrap or configure proper cluster persistence
Permission denied errors: Confirm container capabilities (SYS_ADMIN) are properly configured and Docker daemon is accessible

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

nomad-servernomad-clientconsul

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download