# hc-install An **experimental** Go module for downloading or locating HashiCorp binaries, verifying signatures and checksums, and asserting version constraints. This module is a successor to tfinstall, available in pre-1.0 versions of [terraform-exec](https://github.com/hashicorp/terraform-exec). Current users of tfinstall are advised to move to hc-install before upgrading terraform-exec to v1.0.0. ## hc-install is not a package manager This library is intended for use within Go programs or automated environments (such as CIs) which have some business downloading or otherwise locating HashiCorp binaries. The included command-line utility, `hc-install`, is a convenient way of using the library in ad-hoc or CI shell scripting outside of Go. `hc-install` does **not**: - Determine suitable installation path based on target system. e.g. in `/usr/bin` or `/usr/local/bin` on Unix based system. - Deal with execution of installed binaries (via service files or otherwise). - Upgrade existing binaries on your system. - Add nor link downloaded binaries to your `$PATH`. ## API The `Installer` offers a few high-level methods: - `Ensure(context.Context, []src.Source)` to find, install, or build a product version - `Install(context.Context, []src.Installable)` to install a product version ### Sources The `Installer` methods accept number of different `Source` types. Each comes with different trade-offs described below. - `fs.{AnyVersion,ExactVersion,Version}` - Finds a binary in `$PATH` (or additional paths) - **Pros:** - This is most convenient when you already have the product installed on your system which you already manage. - **Cons:** - Only relies on a single version, expects _you_ to manage the installation - _Not recommended_ for any environment where product installation is not controlled or managed by you (e.g. default GitHub Actions image managed by GitHub) - `releases.{LatestVersion,ExactVersion}` - Downloads, verifies & installs any known product from `releases.hashicorp.com` - **Pros:** - Fast and reliable way of obtaining any pre-built version of any product - Allows installation of enterprise versions - **Cons:** - Installation may consume some bandwidth, disk space and a little time - Potentially less stable builds (see `checkpoint` below) - `checkpoint.LatestVersion` - Downloads, verifies & installs any known product available in HashiCorp Checkpoint - **Pros:** - Checkpoint typically contains only product versions considered stable - **Cons:** - Installation may consume some bandwidth, disk space and a little time - Currently doesn't allow installation of old versions or enterprise versions (see `releases` above) - `build.GitRevision` - Clones raw source code and builds the product from it - **Pros:** - Useful for catching bugs and incompatibilities as early as possible (prior to product release). - **Cons:** - Building from scratch can consume significant amount of time & resources (CPU, memory, bandwidth, disk space) - There are no guarantees that build instructions will always be up-to-date - There's increased likelihood of build containing bugs prior to release - Any CI builds relying on this are likely to be fragile ## Example Usage See examples at . ## CLI In addition to the Go library, which is the intended primary use case of `hc-install`, we also distribute CLI. The CLI comes with some trade-offs: - more limited interface compared to the flexible Go API (installs specific versions of products via `releases.ExactVersion`) - minimal environment pre-requisites (no need to compile Go code) - see ["hc-install is not a package manager"](https://github.com/hashicorp/hc-install#hc-install-is-not-a-package-manager) ### Installation Given that one of the key roles of the CLI/library is integrity checking, you should choose the installation method which involves the same level of integrity checks, and/or perform these checks yourself. `go install` provides only minimal to no integrity checks, depending on exact use. We recommend any of the installation methods documented below. #### Homebrew (macOS / Linux) [Homebrew](https://brew.sh) ```sh brew install hashicorp/tap/hc-install ``` #### Linux We support Debian & Ubuntu via apt and RHEL, CentOS, Fedora and Amazon Linux via RPM. You can follow the instructions in the [Official Packaging Guide](https://www.hashicorp.com/official-packaging-guide) to install the package from the official HashiCorp-maintained repositories. The package name is `hc-install` in all repositories. #### Other platforms 1. [Download for the latest version](https://releases.hashicorp.com/hc-install/) relevant for your operating system and architecture. 2. Verify integrity by comparing the SHA256 checksums which are part of the release (called `hc-install__SHA256SUMS`). 3. Install it by unzipping it and moving it to a directory included in your system's `PATH`. 4. Check that you have installed it correctly via `hc-install --version`. You should see the latest version printed to your terminal. ### Usage ```text Usage: hc-install install [options] -version This command installs a HashiCorp product. Options: -version [REQUIRED] Version of product to install. -path Path to directory where the product will be installed. Defaults to current working directory. -log-file Path to file where logs will be written. /dev/stdout or /dev/stderr can be used to log to STDOUT/STDERR. ``` ```sh hc-install install -version 1.3.7 terraform ``` ```sh hc-install: will install terraform@1.3.7 installed terraform@1.3.7 to /current/working/dir/terraform ```