{"id":28566780,"url":"https://github.com/gruntwork-io/gruntwork-installer","last_synced_at":"2025-06-10T15:38:50.140Z","repository":{"id":38848985,"uuid":"58369100","full_name":"gruntwork-io/gruntwork-installer","owner":"gruntwork-io","description":"A script to make it easy to install Gruntwork Modules","archived":false,"fork":false,"pushed_at":"2024-04-24T09:38:54.000Z","size":139,"stargazers_count":91,"open_issues_count":9,"forks_count":57,"subscribers_count":20,"default_branch":"main","last_synced_at":"2024-05-01T11:28:21.431Z","etag":null,"topics":["bash","cross-platform","devops","installer","package-manager"],"latest_commit_sha":null,"homepage":"https://www.gruntwork.io","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gruntwork-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-05-09T10:39:40.000Z","updated_at":"2024-04-24T09:37:34.000Z","dependencies_parsed_at":"2024-04-24T10:49:49.790Z","dependency_job_id":"868df153-ec13-4c98-8fec-e54cf79546b8","html_url":"https://github.com/gruntwork-io/gruntwork-installer","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgruntwork-installer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgruntwork-installer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgruntwork-installer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgruntwork-installer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gruntwork-io","download_url":"https://codeload.github.com/gruntwork-io/gruntwork-installer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgruntwork-installer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259104037,"owners_count":22805794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","cross-platform","devops","installer","package-manager"],"created_at":"2025-06-10T15:38:49.398Z","updated_at":"2025-06-10T15:38:50.107Z","avatar_url":"https://github.com/gruntwork-io.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Maintained by Gruntwork.io](https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg)](https://gruntwork.io/?ref=repo_gruntwork_installer)\n# Gruntwork Installer\n\n`gruntwork-install` is a bash script you run to easily download and install Gruntwork Modules.\n\n## Compatibility\n\nTested under CentOS 7, latest Amazon Linux, and Ubuntu 16.04.\n\n## Quick Start\n\n### Install gruntwork-install\n\nIf `gruntwork-install` is our approach for installing Gruntwork Modules, how do we install `gruntwork-install` itself?\n\nOur solution is to make the `gruntwork-install` tool open source and to publish a `bootstrap-gruntwork-installer.sh`\nscript that anyone can use to install `gruntwork-install` itself. To use it, execute the following:\n\n```\ncurl -LsS https://raw.githubusercontent.com/gruntwork-io/gruntwork-installer/v0.0.38/bootstrap-gruntwork-installer.sh | bash /dev/stdin --version v0.0.38\n```\n\nNotice the `--version` parameter at the end where you specify which version of `gruntwork-install` to install. See the\n[releases](https://github.com/gruntwork-io/gruntwork-installer/releases) page for all available versions.\n\nFor those concerned about security, see [is it safe to pipe URLs into bash?](#is-it-safe-to-pipe-urls-into-bash) below.\n\n### Use gruntwork-install\n\n#### Authentication\n\nTo install scripts and binaries from private GitHub repos, you must create a [GitHub access\ntoken](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) and set it as the environment\nvariable `GITHUB_OAUTH_TOKEN` so `gruntwork-install` can use it to access the repo:\n\n```\nexport GITHUB_OAUTH_TOKEN=\"(your secret token)\"\n```\n\n#### Options\n\nOnce that environment variable is set, you can run `gruntwork-install` with the following options:\n\nOption                      | Required | Description\n--------------------------- | -------- | ------------\n`--repo`                    | Yes      | The GitHub repo to install from.\n`--tag`                     | Yes      | The version of the `--repo` to install from.\u003cbr\u003eFollows the syntax described at [Tag Constraint Expressions](https://github.com/gruntwork-io/fetch#tag-constraint-expressions). This value is exposed to module install scripts as GRUNTWORK_INSTALL_TAG.\n`--module-name`             | XOR      | The name of a module to install.\u003cbr\u003eCan be any folder within the `modules` directory of `--repo`.\u003cbr\u003eYou must specify exactly one of `--module-name` or `--binary-name`.\n`--binary-name`             | XOR      | The name of a binary to install.\u003cbr\u003eCan be any file uploaded as a release asset in `--repo`.\u003cbr\u003eYou must specify exactly one of `--module-name` or `--binary-name`.\n`--binary-sha256-checksum`  | No       | The SHA256 checksum of the binary specified by `--binary-name`. Should be exactly 64 characters..\n`--binary-sha512-checksum`  | No       | The SHA512 checksum of the binary specified by `--binary-name`. Should be exactly 128 characters..\n`--module-param`            | No       | A key-value pair of the format `key=value` you wish to pass to the module as a parameter. May be used multiple times. \u003cbr\u003eNote: a `--` will automatically be appended to the `key` when your module is invoked\u003cbr\u003eSee the documentation for each module to find out what parameters it accepts.\n`--download-dir`            | No       | The directory to which the module will be downloaded and from which it will be installed.\n`--binary-install-dir`      | No       | The directory to which the binary will be installed. Only applies to binaries (not modules). Default: DEFAULT_BIN_DIR.\n`--no-sudo`                 | No       | When true, don't use sudo to install the binary into the install directory. Only applies to binaries (not modules). Default: false.\n`--branch`                  | No       | Download the latest commit from this branch in --repo. This is an alternative to --tag,\u003cbr\u003eand is used only for testing. This value is exposed to module install scripts as GRUNTWORK_INSTALL_BRANCH.\n`--ref`                     | No       | Download the latest commit from this ref in --repo. This is an alternative to --tag,\u003cbr\u003eand is used only for testing. This value is exposed to module install scripts as GRUNTWORK_INSTALL_BRANCH.\n`--help`                    | No       | Show the help text and exit.\n\n#### Examples\n\n##### Example 1: Download and Install a Script Module with No Parameters\n\nInstall the [ecs-scripts\nmodule](https://github.com/gruntwork-io/terraform-aws-ecs/tree/main/modules/ecs-scripts) from the [terraform-aws-ecs\nrepo](https://github.com/gruntwork-io/terraform-aws-ecs), version `v0.0.1`:\n\n```\ngruntwork-install --module-name 'ecs-scripts' --repo 'https://github.com/gruntwork-io/terraform-aws-ecs' --tag 'v0.0.1'\n```\n\n##### Example 2: Download and Install a Script Module with Parameters\n\nInstall the [fail2ban\nmodule](https://github.com/gruntwork-io/terraform-aws-security/tree/main/modules/fail2ban) from the [terraform-aws-security\nrepo](https://github.com/gruntwork-io/terraform-aws-security), passing two custom parameters to it:\n\n\n```\ngruntwork-install --module-name 'fail2ban' --repo 'terraform-aws-security' --module-param 'ban-time=3600'\n```\n\n##### Example 3: Download and Install a Binary Module\n\nInstall the `gruntkms` binary from the `v0.0.1` release of the [gruntkms\nrepo](https://github.com/gruntwork-io/gruntkms):\n\n```\ngruntwork-install --binary-name 'gruntkms' --repo 'https://github.com/gruntwork-io/gruntkms' --tag 'v0.0.1'\n```\n\nNote that the [v0.0.1 release of the gruntkms repo](https://github.com/gruntwork-io/gruntkms/releases/tag/v0.0.1) has\nmultiple binaries (`gruntkms_linux_amd64`, `gruntkms_darwin_386`, etc): `gruntwork-install` automatically picks the\nright binary for your OS and copies it to `/usr/local/bin/gruntkms`.\n\n##### Example 4: Use `gruntwork-install` in a Packer template\n\nFinally, to put all the pieces together, here is an example of a Packer template that installs `gruntwork-install`\nand then uses it to install several modules:\n\n```json\n{\n  \"variables\": {\n    \"github_auth_token\": \"{{env `GITHUB_OAUTH_TOKEN`}}\"\n  },\n  \"builders\": [\n    {\n      \"ami_name\": \"gruntwork-install-example-{{isotime | clean_ami_name}}\",\n      \"instance_type\": \"t2.micro\",\n      \"region\": \"us-east-1\",\n      \"type\": \"amazon-ebs\",\n      \"source_ami\": \"ami-fce3c696\",\n      \"ssh_username\": \"ubuntu\"\n    }\n  ],\n  \"provisioners\": [\n    {\n      \"type\": \"shell\",\n      \"inline\":\n        \"curl -Ls https://raw.githubusercontent.com/gruntwork-io/gruntwork-installer/v0.0.38/bootstrap-gruntwork-installer.sh | bash /dev/stdin --version v0.0.16\"\n    },\n    {\n      \"type\": \"shell\",\n      \"inline\": [\n        \"gruntwork-install --module-name 'ecs-scripts' --repo 'https://github.com/gruntwork-io/terraform-aws-ecs' --tag 'v0.0.1'\",\n        \"gruntwork-install --module-name 'fail2ban' --repo 'https://github.com/gruntwork-io/terraform-aws-security' -module-param 'ban-time=3600'\",\n        \"gruntwork-install --binary-name 'gruntkms' --repo 'https://github.com/gruntwork-io/gruntkms' --tag 'v0.0.1'\"\n      ],\n      \"environment_vars\": [\"GITHUB_OAUTH_TOKEN={{user `github_auth_token`}}\"]\n    }\n  ]\n}\n```\n\n## Motivation\n\nAt [Gruntwork](http://www.gruntwork.io/), we've developed a number of scripts and binaries, most of them in private GitHub\nrepos, that perform common infrastructure tasks such as setting up continuous integration, monitoring, log aggregation,\nand SSH access. Being able to use these \"modules\" of code typically involves many steps: you download the files\n(possibly from a private GitHub repo), change their permissions, and run them with the parameters that make sense for\nyour environment.\n\nThat basically means lots of custom `bash` code copied differently across multiple software teams in multiple different\ncontexts. Worse, if we want to update a binary or script to add a new parameter, each team has to modify their own custom\ncode, which can be painful.\n\nWe believe we can do better by writing our scripts and binaries in a standardized way, and including a minimal tool that\nstreamlines the process of downloading and installing them. Also, since we give you 100% of the source code, we want it\nto be clear exactly what happens when you install a Gruntwork Module.\n\nFinally, installation should be streamlined no matter what platform (Windows, MacOS, Linux) you're on. Indeed, our goal\nis to make installing Gruntwork Script Modules as easy as installing a typical package using `apt-get`, `yum`, `npm`,\nor similar tools. We would have just used these existing tools, but none offer multi-platform compatibility.\n\n## What's a Gruntwork Module?\n\nA Gruntwork Module is a collection of one or more bash scripts and/or binaries maintained by Gruntwork that can be used to\nadd functionality to or configure an environment. There are multiple types of Gruntwork Modules:\n\n* **Script Modules:** A collection of one or more files and scripts; installed with an `install.sh` script.\n* **Binary Modules:** A single OS-specific executable binary.\n\nAdditional module types may be introduced in the future.\n\nAs an example, we have Script Modules for installing a CloudWatch Logs agent, optimizing syslog settings, and setting up\nautomatic security updates. We have a Binary Module for streamlining the use of Amazon Key Management Service (KMS).\n\nGruntwork sells [Infrastructure Packages](https://blog.gruntwork.io/gruntwork-infrastructure-packages-7434dc77d0b1#.6bwor6wxc).\nEach Infrastructure Package corresponds to a specific GitHub repo and contains one or more Gruntwork Modules. The `/modules`\nfolder in the repo lists all Modules included with that Package.\n\n### Freely Available Script Modules\n\nSome Script Modules are so common that we've made them freely available in the [modules/](modules) folder of this repo.\n\n### How `gruntwork-install` Works\n\n`gruntwork-install` helps you install a Gruntwork Module. Here's how it works:\n\n1. It uses [fetch](https://github.com/gruntwork-io/fetch) to download the specified version of the scripts or binary from\nthe (public or private) git repo specified via the `--repo` option.\n1. You need to specify either a module name or a binary name. \n  - If you use the `--module-name` parameter, it downloads the files from the `modules` folder of `--repo` and runs\nthe `install.sh` script of that module.\n  - If you use the `--binary-name` parameter, it downloads the right binary for your OS, copies it to `/usr/local/bin`,\nand gives it execute permissions.\n\n## Create Your Own Gruntwork Modules\n\nYou can use `gruntwork-install` with any GitHub repo, not just repos maintained by Gruntwork.\n\nThat means that to create an installable Script Module, all you have to do is put it in the `modules` folder of\na GitHub repo to which you have access and include an `install.sh` script. To create a Binary Module, you just publish\nit to a GitHub release with the name format `\u003cNAME\u003e_\u003cOS\u003e_\u003cARCH\u003e`.\n\n### Example\n\nFor example, in your Packer and Docker templates, you can use `gruntwork-install` to install the [ecs-scripts\nmodule](https://github.com/gruntwork-io/terraform-aws-ecs/tree/main/modules/ecs-scripts) as follows:\n\n```\ngruntwork-install --module-name 'ecs-scripts' --repo 'https://github.com/gruntwork-io/terraform-aws-ecs' --tag 'v0.0.1'\n```\n\nIn https://github.com/gruntwork-io/module-ecs, we download the contents of `/modules/ecs-scripts` and run\n`/modules/ecs-scripts/install.sh`.\n\n## Running tests\n\nThe tests for this repo are defined in the `test` folder. They are designed to run in a Docker container so that you\ndo not repeatedly dirty up your local OS while testing. We've defined a `test/docker-compose.yml` file as a convenient\nway to expose the environment variables we need for testing and to mount local directories as volumes for rapid\niteration.\n\nTo run the tests:\n\n1. Set your [GitHub access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) as\n   the environment variable `GITHUB_OAUTH_TOKEN`.\n1. `./_ci/run-tests.sh`\n\n## Security\n\n### Validate the Downloaded Binary\n\n`gruntwork-install` will retrieve the desired GitHub Release Asset specified by the `--binary-name` property, but how \ncan we confirm that this binary has not been tampered with? In short, we trust that the maintainer has been responsible\nand not allowed a malicious third-party to corrupt the Release Asset.\n\nYou can narrow the scope of this trust by computing a checksum on a Release Asset using a UNIX command like\n`shasum -a 256 /path/to/file` when you first download the release. You can then feed this value (e.g. `b0b30cc24aed1b8cded2df903183b884c77f086efffc36ef19876d1c55fef93d`)\nto `--binary-sha256-checksum` or `--binary-sha512-checksum`. If the checksum does not match, gruntwork-install will fail\nwith an error. This way, you are at least notified if the Release Asset you initially downloaded has since been changed.\n\n### Is it safe to pipe URLs into bash?\n\nAre you worried that our install instructions tell you to pipe a URL into bash? Although this approach has seen some\n[backlash](https://news.ycombinator.com/item?id=6650987), we believe that the convenience of a one-line install\noutweighs the minimal security risks. Below is a brief discussion of the most commonly discussed risks and what you can\ndo about them.\n\n#### Risk #1: You don't know what the script is doing, so you shouldn't blindly execute it.\n\nThis is true of _all_ installers. For example, have you ever inspected the install code before running `apt-get install`\nor `brew install` or double clicking a `.dmg` or `.exe` file? If anything, a shell script is the most transparent\ninstaller out there, as it's one of the few that allows you to inspect the code (feel free to do so, as this script is\nopen source!). The reality is that you either trust the developer or you don't. And eventually, you automate the\ninstall process anyway, at which point manual inspection isn't a possibility anyway.\n\n#### Risk #2: The download URL could be hijacked for malicious code.\n\nThis is unlikely, as it is an https URL, and your download program (e.g. `curl`) should be verifying SSL certs. That\nsaid, Certificate Authorities have been hacked in the past, and perhaps the Gruntwork GitHub account could be hacked\nin the future, so if that is a major concern for you, feel free to copy the bootstrap code into your own codebase and\nexecute it from there. Alternatively, in the future we will publish checksums of all of our releases, so you could\noptionally verify the checksum before executing the script.\n\n#### Risk #3: The script may not download fully and executing it could cause errors.\n\nWe wrote our [bootstrap-gruntwork-installer.sh](bootstrap-gruntwork-installer.sh) as a series of bash functions that\nare only executed by the very last line of the script. Therefore, if the script doesn't fully download, the worst\nthat'll happen when you execute it is a harmless syntax error.\n\n## TODO\n\n1. Configure a CI build to automatically set the `--version` flag for each release.\n1. Add an `uninstall` command that uses an `uninstall.sh` script in each module.\n1. Add support for modules declaring their dependencies. Alternatively, consider Nix again as a dependency manager.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgruntwork-io%2Fgruntwork-installer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgruntwork-io%2Fgruntwork-installer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgruntwork-io%2Fgruntwork-installer/lists"}