Installing Nomad

Nomad is available as a pre-compiled binary or as a package for several operating systems. You can also build Nomad from source.

If you are interested in trialing Nomad without installing it locally, see the Quickstart for options to get started with Nomad.

You can download a precompiled binary and run it on your machine locally. You can also verify the binary using the available SHA-256 sums. After downloading Nomad, unzip the package. Make sure that the nomad binary is available on your PATH before continuing with the other guides.

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 | sudo gpg --dearmor -o /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 Consul and Vault 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.5.0/cni-plugins-linux-$( [ $(uname -m) = aarch64 ] && echo arm64 || echo amd64)"-v1.5.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.

net.bridge.bridge-nf-call-arptables = 1net.bridge.bridge-nf-call-ip6tables = 1net.bridge.bridge-nf-call-iptables = 1

Verify cgroup controllers

On Linux, Nomad uses cgroups to control resource usage of tasks. If one or more required cgroups are unavailable, Nomad will disable resource controls that require cgroups entirely. With cgroups v2, you can verify that you have all required controllers as follows:

$ cat /sys/fs/cgroup/cgroup.controllerscpuset cpu io memory pids

See the documentation on cgroup controller requirements for more details.

Add the Nomad binary to your system path

Note that if you are running Nomad on Linux, you'll need to run client agents as root (or with sudo) so that cpuset accounting and network namespaces work correctly.

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.

net.bridge.bridge-nf-call-arptables = 1net.bridge.bridge-nf-call-ip6tables = 1net.bridge.bridge-nf-call-iptables = 1

Verify cgroup controllers

$ cat /sys/fs/cgroup/cgroup.controllerscpuset cpu io memory pids

See the documentation on cgroup controller requirements for more details.

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 agentOther commands:    acl                 Interact with ACL policies and tokens    agent-info          Display status information about the local agent    config              Interact with configurations    deployment          Interact with deployments    eval                Interact with evaluations    exec                Execute commands in task    fmt                 Rewrites Nomad config and job files to canonical format    license             Interact with Nomad Enterprise License    login               Login to Nomad using an auth method    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    service             Interact with registered services    system              Interact with the system API    tls                 Generate Self Signed TLS Certificates for Nomad    ui                  Open the Nomad Web UI    var                 Interact with variables    version             Prints the Nomad version    volume              Interact with volumes

Compiling from Source

To compile from source, you will need Go installed at the version described by the .go-version file. You should properly configure your Go environment, including setting a GOPATH environment variable and ensuring GOPATH/bin is within your PATH. A copy of git is also needed in your PATH.

Clone the Nomad repository from GitHub into your GOPATH:

$ mkdir -p $GOPATH/src/github.com/hashicorp && cd $_$ git clone https://github.com/hashicorp/nomad.git$ cd nomad

Bootstrap the project. This will download and compile libraries and tools needed to compile Nomad:
```
$ make bootstrap
```
Build Nomad for your current system and put the binary in ./bin/ (relative to the git checkout). The make dev target is just a shortcut that builds nomad for only your local build environment (no cross-compiled targets).
```
$ make dev
```