Running Docker Containers in HashiCorp Nomad: A Beginner’s Guide

Nomad, a flexible and lightweight orchestrator developed by HashiCorp, is an excellent tool for managing containerized applications like Docker. This guide walks you through running Docker containers with Nomad, designed specifically for beginners. Whether you're deploying a simple web server or experimenting with microservices, this guide will provide you with the foundation to get started.

What Is Nomad?

Nomad is a simple, flexible, and scalable workload orchestrator that supports running containerized and non-containerized applications. Though it is not as popular as Kubernetes, which currently dominates the container orchestration space, Nomad has its advantages: ease of use, lightweight architecture, and support for mixed workloads.

Prerequisites

Before running Docker containers in Nomad, ensure the following:

1. Nomad Installed: Download and install Nomad from HashiCorp's website.
2. Docker Installed: Install Docker and confirm it is running with:
   Plain Text

    

   docker --version

   
   

3. Nomad Agent Running: Start a Nomad agent in development mode for simplicity. The -dev flag starts a local Nomad cluster in development mode:
   Plain Text

    

   nomad agent -dev

   
   

Step 1: Write a Nomad Job File

Nomad uses job specification files written in HashiCorp Configuration Language (HCL) to define the jobs it manages. Below is a basic example of a Nomad job file (docker.nomad) to run an NGINX web server.

Example: Simple Nomad Job File

job "nginx-job" {
  datacenters = ["dc1"]

  group "web-group" {
    count = 1

    task "nginx" {
      driver = "docker"

      config {
        image = "nginx:latest"  # Docker image to run
        ports = ["http"]
      }

      resources {
        network {
          port "http" {
            static = 8080  # Expose container on host's port 8080
          }
        }
      }
    }
  }
}

Explanation of the Job File

• job: Defines the job name and datacenter to deploy to.
• group: Groups related tasks (containers) together.
• task: Specifies a single container to run, including the driver (docker) and configuration.
• config: Contains Docker-specific settings like the image to use and ports to expose.
• resources: Defines resource limits and networking settings for the container.

Step 2: Run the Nomad Job

Submit the job file to the Nomad cluster using the nomad run command:

nomad run docker.nomad

This will schedule the NGINX container on the Nomad agent. If successful, you’ll see output indicating that the job has been successfully deployed.

Step 3: Verify the Job

Check the status of the job using:

nomad status nginx-job

You should see the job details, including its allocation ID and deployment status.

Step 4: Access the Running Container

1. Find the IP address of the host running the container. If you're running locally, it’s likely 127.0.0.1.
2. Open a web browser and visit http://localhost:8080. You should see the default NGINX welcome page.

Step 5: Stop the Job

To stop the container, use the nomad stop command:

nomad stop nginx-job

This will cleanly shut down the container managed by Nomad.

Advanced Examples

1. Add Environment Variables

You can pass environment variables to your Docker container using the env block in the task section:

task "nginx" {
  driver = "docker"

  config {
    image = "nginx:latest"
    ports = ["http"]
  }

  env {
    APP_ENV = "production"
  }
}

2. Mount Volumes

To mount a host directory into the container, use the volumes option in the config block:

task "nginx" {
  driver = "docker"

  config {
    image = "nginx:latest"
    ports = ["http"]
    volumes = ["/host/path:/container/path"]
  }
}

3. Scale Containers

To scale the container to multiple instances, modify the count parameter in the group section:

group "web-group" {
  count = 3  # Run 3 instances of the container
}

Nomad will distribute the instances across available nodes in your cluster.

Tips for Beginners

1. Test in Development Mode: Start with the nomad agent -dev command for quick local testing before deploying to a production cluster.
2. Leverage Nomad's Web UI: Use the Nomad UI (enabled by default in dev mode) to monitor jobs and allocations visually. Access it at http://localhost:4646.
3. Use Logs for Debugging: Check logs for troubleshooting with:
   Plain Text

    

   nomad logs <allocation-id>

Conclusion

Running Docker containers with HashiCorp Nomad is a straightforward and powerful way to orchestrate workloads. By defining jobs in simple HCL files, you can easily deploy, monitor, and scale containers across your infrastructure. Whether you're just starting or looking for an alternative to Kubernetes, Nomad’s simplicity and flexibility make it an excellent choice for managing containerized applications.