• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Nomad
  • Install
  • Intro
  • Tutorials
  • Documentation
  • API
  • Tools
  • Plugins
  • Sign up
CLI Quick Start

Skip to main content
7 tutorials
  • Introduction to Nomad
  • Install Nomad
  • Nomad Vocabulary
  • Start Nomad and Run Your First Job
  • Scale and Update a Job
  • Visit the Web Interface
  • Stop Nomad; Learn More

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Nomad
  3. Tutorials
  4. CLI Quick Start
  5. Install Nomad

Install Nomad

  • 9min

  • NomadNomad

Nomad is an orchestration tool for deploying and managing applications. It is flexible and can run either containerized or non-containerized workloads.

In these getting started guides, you will learn about Nomad's core capabilities by installing and running a local Nomad cluster.

You can install Nomad to your local machine or you can use a pre-built Vagrant environment to run the steps in this tutorial. Choose one of the following ways of installing Nomad, follow the steps, and then continue to "Verify the installation."

Local install

Nomad is available as a pre-compiled binary or as a package for several operating systems.

To simplify the getting started experience, you can download a precompiled binary and run it on your machine locally.

After downloading Nomad, unzip the package. Make sure that the nomad binary is available on your PATH, before continuing with the other guides.

You can inspect the locations available on your path by running this command.

$ echo $PATH
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

The output is a list of locations separated by colons. You can make Nomad available by moving the binary to one of the listed locations, or by adding Nomad's location to your PATH.

Homebrew is a free and open source package management system for Mac OS X. Install the official Nomad formula from the terminal.

First, install the HashiCorp tap, a repository of all of the HashiCorp Homebrew packages.

$ brew tap hashicorp/tap

Now, install Nomad with hashicorp/tap/nomad.

$ brew install hashicorp/tap/nomad

NOTE: This installs a signed binary and is automatically updated with every new official release.

To update to the latest, run

$ brew upgrade hashicorp/tap/nomad

Chocolatey is a free and open source package management system for Windows. Install the Nomad package from the command-line.

$ choco install nomad

NOTE: Chocolatey and the Nomad package are NOT directly maintained by HashiCorp. The latest version of Nomad is always available by manual installation.

HashiCorp officially maintains and signs packages for the following Linux distributions.

Install the required packages.

$ sudo apt-get update && \
  sudo apt-get install wget gpg coreutils

Add the HashiCorp GPG key.

$ wget -O- https://apt.releases.hashicorp.com/gpg | gpg --dearmor | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg

Add the official HashiCorp Linux repository.

$ 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

Update and install.

$ sudo apt-get update && sudo apt-get install nomad

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

Install.

$ sudo yum -y install nomad

Install dnf config-manager to manage your repositories.

$ sudo dnf install -y dnf-plugins-core

Use dnf config-manager to add the official HashiCorp Linux repository.

$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo

Install.

$ sudo dnf -y install nomad

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo

Install.

$ sudo yum -y install nomad

TIP: Now that you have added the HashiCorp repository, you can install Terraform, Vault, Consul, and Packer with the same command.

Post-installation steps

These steps are considered optional but can be helpful for running Nomad and to take advantage of additional Nomad functionalities.

Add the Nomad binary to your system path

Permanently add a new location to your path by editing your shell's settings file (usually called something like ~/.bashrc, where the part of the filename after the . and before rc is the name of your shell). In that file you should see a line that starts with export PATH=, followed by a colon-separated list of locations. Add the location of the Nomad binary to that list and save the file. Then reload your shell's configuration with the command source ~/.bashrc, replacing bash with the name of your shell.

Install CNI plugins

Nomad uses CNI plugins to configure network namespaces when using the bridge network mode. All Linux Nomad client nodes using network namespaces must have CNI plugins installed.

The following commands install the CNI reference plugins.

$ curl -L -o cni-plugins.tgz "https://github.com/containernetworking/plugins/releases/download/v1.0.0/cni-plugins-linux-$( [ $(uname -m) = aarch64 ] && echo arm64 || echo amd64)"-v1.0.0.tgz && \
  sudo mkdir -p /opt/cni/bin && \
  sudo tar -C /opt/cni/bin -xzf cni-plugins.tgz

Ensure your Linux operating system distribution has been configured to allow container traffic through the bridge network to be routed via iptables. These tunables can be set as follows.

$ echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-arptables && \
  echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-ip6tables && \
  echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-iptables

To preserve these settings on startup of a client node, add a file including the following to /etc/sysctl.d/ or remove the file your Linux distribution puts in that directory.

/etc/sysctl.d/bridge.conf
net.bridge.bridge-nf-call-arptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1

Add the Nomad binary to your system path

Permanently add a new location to your path by editing your shell's settings file (usually called something like ~/.bashrc, where the part of the filename after the . and before rc is the name of your shell). In that file you should see a line that starts with export PATH=, followed by a colon-separated list of locations. Add the location of the Nomad binary to that list and save the file. Then reload your shell's configuration with the command source ~/.bashrc, replacing bash with the name of your shell.

Add the Nomad binary to your system path

Add a location to your path via the GUI by navigating to Environment Variables in your system settings, and looking for the variable called PATH. You should see a semicolon-separated list of locations. Add the Nomad binary's location to that list and then launch a new console window.

No additional steps necessary after installing Nomad using Homebrew.
No additional steps necessary after installing Nomad using Chocolatey.

Install CNI plugins

Nomad uses CNI plugins to configure network namespaces when using the bridge network mode. All Linux Nomad client nodes using network namespaces must have CNI plugins installed.

The following commands install the CNI reference plugins.

$ curl -L -o cni-plugins.tgz "https://github.com/containernetworking/plugins/releases/download/v1.0.0/cni-plugins-linux-$( [ $(uname -m) = aarch64 ] && echo arm64 || echo amd64)"-v1.0.0.tgz && \
  sudo mkdir -p /opt/cni/bin && \
  sudo tar -C /opt/cni/bin -xzf cni-plugins.tgz

Ensure your Linux operating system distribution has been configured to allow container traffic through the bridge network to be routed via iptables. These tunables can be set as follows.

$ echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-arptables && \
  echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-ip6tables && \
  echo 1 | sudo tee /proc/sys/net/bridge/bridge-nf-call-iptables

To preserve these settings on startup of a client node, add a file including the following to /etc/sysctl.d/ or remove the file your Linux distribution puts in that directory.

/etc/sysctl.d/bridge.conf
net.bridge.bridge-nf-call-arptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1

Use Vagrant

You can use a Vagrant to set up a development environment for Nomad. Vagrant is a tool for building and managing virtual machine environments.

NOTE: To use the Vagrant environment, first install Vagrant following these instructions. You also need a virtualization tool, such as VirtualBox.

You can download a Vagrantfile which starts a small Nomad cluster. First create a new directory for your Vagrant environment.

$ mkdir nomad-demo

Change into the directory you made with the previous command.

$ cd nomad-demo

Now you can get the Nomad installation configuration.

$ curl -O https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/Vagrantfile

Now that you have created a new directory and downloaded the Vagrantfile you must create the virtual machine with the vagrant up command.

$ vagrant up

This takes a few minutes as the base Ubuntu box must be downloaded and provisioned with both Docker and Nomad. Once this completes, you should see this output.

Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'bento/ubuntu-18.04'...
...
==> default: Running provisioner: docker...

At this point the Vagrant box is running and ready to use. Once the Vagrant box is running, use the vagrant ssh command to start a shell session on it.

$ vagrant ssh

If you connect to the virtual machine properly, you should find yourself at a shell prompt for vagrant@nomad:~$

Verify the installation

To verify Nomad was installed correctly, try the nomad command.

$ nomad

You should see help output similar to the following.

Usage: nomad [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    run         Run a new job or update an existing job
    stop        Stop a running job
    status      Display the status output for a resource
    alloc       Interact with allocations
    job         Interact with jobs
    node        Interact with nodes
    agent       Runs a Nomad agent

Other commands:
    acl                 Interact with ACL policies and tokens
    agent-info          Display status information about the local agent
    deployment          Interact with deployments
    eval                Interact with evaluations
    exec                Execute commands in task
    license             Interact with Nomad Enterprise License
    monitor             Stream logs from a Nomad agent
    namespace           Interact with namespaces
    operator            Provides cluster-level tools for Nomad operators
    plugin              Inspect plugins
    quota               Interact with quotas
    recommendation      Interact with the Nomad recommendation endpoint
    scaling             Interact with the Nomad scaling endpoint
    sentinel            Interact with Sentinel policies
    server              Interact with servers
    system              Interact with the system API
    ui                  Open the Nomad Web UI
    version             Prints the Nomad version
    volume              Interact with volumes

Next steps

In this tutorial you installed Nomad on your local machine. Continue to the next guide where you will be introduced to some of the critical vocabulary related to Nomad.

 Previous
 Next

On this page

  1. Install Nomad
  2. Local install
  3. Post-installation steps
  4. Use Vagrant
  5. Verify the installation
  6. Next steps
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)