From 92a2a0429e938f4e670957f26a04a4d86e9f3313 Mon Sep 17 00:00:00 2001 From: Charlie Voiselle <464492+angrycub@users.noreply.github.com> Date: Fri, 7 Aug 2020 16:27:17 -0400 Subject: [PATCH] [docs] Updating install instructions to add packages. (#8534) * Updated install, added packages * Apply suggestions from code review Co-authored-by: Michael Schurter --- website/pages/docs/install/index.mdx | 242 ++++++++++++++++-- .../pages/docs/install/quickstart/index.mdx | 86 ++++++- 2 files changed, 290 insertions(+), 38 deletions(-) diff --git a/website/pages/docs/install/index.mdx b/website/pages/docs/install/index.mdx index 8be776939..6e5600215 100644 --- a/website/pages/docs/install/index.mdx +++ b/website/pages/docs/install/index.mdx @@ -7,28 +7,223 @@ description: Learn how to install Nomad. # Installing Nomad -Installing Nomad is simple. There are two approaches to 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](#from-source). -1. Using a [precompiled binary](#precompiled-binaries) -1. Installing [from source](#from-source) +-> If you are interested in trialing Nomad without installing it locally, see the +[Quickstart](/docs/install/quickstart) for options to get started with Nomad. -Downloading a precompiled binary is easiest, and we provide downloads over -TLS along with SHA-256 sums to verify the binary. + + -## Precompiled Binaries ((#precompiled-binaries)) +You can download a [precompiled binary](https://nomadproject.io/downloads/) 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. -To install the precompiled binary, -[download](/downloads) the appropriate package for your system. -Nomad is currently packaged as a zip file. We do not have any near term -plans to provide system packages. +You can check the locations available on your path by running this command. -Once the zip is downloaded, unzip it into any directory. The -`nomad` (or `nomad.exe` for Windows) binary inside is all that is -necessary to run Nomad. Any additional files, if any, are not -required to run Nomad. +```shell-session +$ echo $PATH -Copy the binary to anywhere on your system. If you intend to access it -from the command-line, make sure to place it somewhere on your `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`. + +-> **Tip (Linux-based or Mac):** 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 file name after the `.` and before `rc` is the name of +your shell). In that file you will see a line that starts with `export PATH=`, +followed by a colon-separated list of locations. Add the location of the Consul +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. + +-> **Tip (Windows):** 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 will see a semicolon-separated list of locations. Add the +Nomad binary's location to that list and then launch a new console window. + + + + +HashiCorp officially maintains and signs packages for the following Linux +distributions. + + + + +Add the HashiCorp [GPG key][gpg-key]. + +```shell-session +$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add - +``` + +Add the official HashiCorp Linux repository. + +```shell-session +$ sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main" +``` + +Update and install. + +```shell-session +$ sudo apt-get update && sudo apt-get install nomad +``` + + + + +Install `yum-config-manager` to manage your repositories. + +```shell-session +$ sudo yum install -y yum-utils +``` + +Use `yum-config-manager` to add the official HashiCorp Linux repository. + +```shell-session +$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo +``` + +Install. + +```shell-session +$ sudo yum -y install nomad +``` + + + + +Install `dnf config-manager` to manage your repositories. + +```shell-session +$ sudo dnf install -y dnf-plugins-core +``` + +Use `dnf config-manager` to add the official HashiCorp Linux repository. + +```shell-session +$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo +``` + +Install. + +```shell-session +$ sudo dnf -y install nomad +``` + + + + +Install `yum-config-manager` to manage your repositories. + +```shell-session +$ sudo yum install -y yum-utils +``` + +Use `yum-config-manager` to add the official HashiCorp Linux repository. + +```shell-session +$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo +``` + +Install. + +```shell-session +$ sudo yum -y install nomad +``` + + + + +-> **TIP:** Now that you have added the HashiCorp repository, you can install +[Consul](https://learn.hashicorp.com/consul) and +[Vault](https://learn.hashicorp.com/vault) with the same command. + + + + +[Homebrew](https://brew.sh) is a free and open-source package management system +for macOS. Install the [Nomad formula](https://formulae.brew.sh/formula/nomad) +from the terminal. + +```shell-session +$ brew install nomad +``` + +~> **NOTE:** Homebrew and the Nomad formula are **NOT** directly maintained by +HashiCorp. The latest version of Nomad is always available by manual +installation. + +~> **NOTE**: On macOS, machines without a Java environment installed will be +prompted to install Java because of a [known issue—#7865][gh-7865]. The linked +GitHub issue has workarounds for this issue. + + + + +[Chocolatey](https://chocolatey.org/) is a free and open-source package +management system for Windows. Install the [Nomad +package](https://chocolatey.org/packages/nomad) from the command-line. + +```shell-session +$ 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. + + + + +--- + +## Verify the Installation + +To verify Nomad was installed correctly, try the `nomad` command. + +```shell-session +$ nomad +``` + +You should see help output, similar to the following. + +```plaintext +Usage: nomad [-version] [-help] [-autocomplete-(un)install] [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 + monitor Stream logs from a Nomad agent + namespace Interact with namespaces + operator Provides cluster-level tools for Nomad operators + quota Interact with quotas + 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 +``` + +--- ## Compiling from Source ((#from-source)) @@ -60,13 +255,8 @@ as a copy of [`git`](https://www.git-scm.com/) in your `PATH`. $ make dev ``` -## Verifying the Installation - -To verify Nomad is properly installed, run `nomad -v` on your system. You should -see help output. If you are executing it from the command line, make sure it is -on your `PATH` or you may get an error about `nomad` not being found. - -```shell-session -$ nomad -v - -``` +[consul-dev]: https://learn.hashicorp.com/consul/getting-started/agent#starting-the-agent +[consul-download]: https://www.consul.io/downloads.html +[destroy]: https://www.vagrantup.com/docs/cli/destroy.html +[gh-7865]: https://github.com/hashicorp/nomad/issues/7865 +[gpg-key]: https://apt.releases.hashicorp.com/gpg 'HashiCorp GPG key' diff --git a/website/pages/docs/install/quickstart/index.mdx b/website/pages/docs/install/quickstart/index.mdx index 26fcf8135..ea30f4dfe 100644 --- a/website/pages/docs/install/quickstart/index.mdx +++ b/website/pages/docs/install/quickstart/index.mdx @@ -12,32 +12,94 @@ environment. These installations are designed to get you started with Nomad easily and should be used only for experimentation purposes. If you are looking to install Nomad -in production, please refer to our [Production -Installation](/docs/install/production) guide here. +in production, please refer to our [Production Installation](/docs/install/production) guide here. -## Local + + -Install Nomad on your local machine. +Experiment with Nomad in your browser via the Katacoda interactive learning platform. -- [Installing the Pre-compiled Binary][installing-binary] -- [Installing Nomad with Vagrant][vagrant-environment] +- [Introduction to Nomad](https://www.katacoda.com/hashicorp/scenarios/nomad-introduction) -## Cloud +- [Nomad Playground](https://katacoda.com/hashicorp/scenarios/playground) + + + Install Nomad on the public cloud. - AWS + - [CloudFormation](https://aws.amazon.com/quickstart/architecture/nomad/) + - [Terraform](https://github.com/hashicorp/nomad/blob/master/terraform/aws/README.md) + - Azure + - [Terraform](https://github.com/hashicorp/nomad/tree/master/terraform/azure) -## Katacoda + + -Experiment with Nomad in your browser via KataCoda's interactive learning platform. +## Install Nomad on your machine -- [Introduction to Nomad](https://www.katacoda.com/hashicorp/scenarios/nomad-introduction) -- [Nomad Playground](https://katacoda.com/hashicorp/scenarios/playground) +If you would like to try Nomad locally, you can install Nomad on your local +machine using the same steps that you would for a production environments and +run a single-node development instance using the `nomad agent -dev` command -[installing-binary]: /docs/install/#precompiled-binaries +[Installing Nomad][installing-binary] + +## Run Nomad in Vagrant + +Alternatively, 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](https://www.vagrantup.com/docs/installation/). You will +also need a virtualization tool, such as [VirtualBox][]. + +You can download a Vagrantfile which will start a small Nomad cluster. First +create a new directory for your Vagrant environment. + +```shell-session +$ mkdir nomad-vagrant +``` + +Change into the directory you made with the previous command. + +```shell-session +$ cd nomad-vagrant +``` + +Now you can get the Nomad installation configuration. + +```shell-session +$ 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. + +```shell-session +$ vagrant up +``` + +This will take 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. + +```plaintext +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 go. + + + + +[installing-binary]: /docs/install [vagrant-environment]: https://learn.hashicorp.com/nomad/getting-started/install#vagrant-setup-optional +[virtualbox]: https://www.virtualbox.org/