Packages

<!-- markdownlint-disable -->

<a href="https://cpco.io/homepage"><img src="https://github.com/cloudposse/packages/blob/main/.github/banner.png?raw=true" alt="Project Banner"/></a><br/>

<p align="right"><a href="https://github.com/cloudposse/packages/actions/workflows/auto-update-packages.yml"><img src="https://github.com/cloudposse/packages/actions/workflows/auto-update-packages.yml/badge.svg" alt="Auto Update Status"/></a><a href="https://slack.cloudposse.com"><img src="https://slack.cloudposse.com/badge.svg" alt="Slack Community"/></a> </p> <!-- markdownlint-restore --> <!-- ** DO NOT EDIT THIS FILE ** ** This file was automatically generated by the `cloudposse/build-harness`. ** 1) Make all changes to `README.yaml` ** 2) Install [atmos](https://atmos.tools/install/) (you only need to do this once) ** 3) Run`atmos readme` to rebuild this file. ** ** (We maintain HUNDREDS of open source projects. This is how we maintain our sanity.) ** -->

Cloud Posse distribution of awesome apps.

Introduction

Use this repo to easily install releases of popular Open Source apps. We provide a few ways to use it.

1. Make Based Installer. This installer works regardless of your OS and distribution. It downloads packages directly from their GitHub source repos and installs them to your INSTALL_PATH.
2. Alpine Linux Packages. Use our Alpine repository to install prebuilt packages that use the original source binary (where possible) from the maintainers' official GitHub repo releases.
3. Docker Image. Use our docker image as a base-image or as part of a multi-stage docker build. The docker image always distributes the latest linux binaries for x86_64 architectures.

See examples below for usage.

Is one of our packages out of date?

Open up an issue or submit a PR (preferred). We'll review quickly!

Sponsorship <img src="https://cloudposse.com/wp-content/uploads/2020/10/cloudsmith.svg" width="250" align="right" />

Package repository hosting is graciously provided by cloudsmith. Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that enables your organization to create, store and share packages in any format, to any place, with total confidence. We believe there’s a better way to manage software assets and packages, and they’re making it happen!

Usage

Debian Repository (recommended)

A public Debian repository is provided by Cloud Posse. The repository is hosted by Cloudsmith Using this Debian repository is ultimately more reliable than depending on GitHub for availability and provides an easier way to manage dependencies pinned at multiple versions.

Configure the Debian repository:

The Easy Way

Cloudsmith provides an installation script to configure the Debian repository for your version of Debian.

curl -1sLf 'https://dl.cloudsmith.io/public/cloudposse/packages/cfg/setup/bash.deb.sh' | bash

NOTE: Requires bash and curl to run:

For Docker

Add the following to your Dockerfile near the top.

# Install the cloudposse Debian repository
RUN apt-get update && apt-get install -y apt-utils curl
RUN curl -1sLf 'https://dl.cloudsmith.io/public/cloudposse/packages/cfg/setup/bash.deb.sh' | bash

Installing Debian Packages

When adding packages, we recommend using apt-get update && apt-get install -yq $package to update the repository index before installing packages.

Simply install any package as normal:

apk-get install -y terraform

But we recommend that you use version pinning (the -\* is important, as it gets you the latest version of the package):

apt-get install gomplate=3.0.0-\*

RPM Repository

We publish RPM packages corresponding to all the Debian packages we publish. Installing the repository is almost the same as above.

curl -1sLf 'https://dl.cloudsmith.io/public/cloudposse/packages/cfg/setup/bash.rpm.sh' | bash

Install packages as normal. yum automatically updates the repository index before installing packages.

yum install -y terraform

Note that unlike other package systems, yum automatically updates the repository index before installing packages.

We still recommend version pinning, but yum makes it hard. You can use this command to list all the available versions of a package:

yum --showduplicate list $package

Then you can install the package with a version pinning:

VERSION=1.3.0
RELEASE=1
yum install -y $package-$VERSION-$RELEASE.$(uname -m)

Alpine Repository

A public Alpine repository is provided by Cloud Posse. The repository is hosted by Cloudsmith Using this Alpine repository is ultimately more reliable than depending on GitHub for availability and provides an easier way to manage dependencies pinned at multiple versions.

Configure the Alpine repository:

The Easy Way

Cloudsmith provides an installation script to configure the Alpine repository for your version of Alpine.

apk add --no-cache bash curl
curl -1sLf \
'https://dl.cloudsmith.io/public/cloudposse/packages/setup.alpine.sh' \
| bash  

Installing Alpine Packages

When adding packages, we recommend using apk add --update $package to update the repository index before installing packages.

Simply install any package as normal:

apk add --update terraform

But we recommend that you use version pinning:

apk add --update terraform==1.0.0-r0

And maybe even repository pinning, so you know that you get our versions:

apk add --update terraform@cloudposse==1.0.0-r0

Makefile Interface

The Makefile interface works on OSX and Linux. It's a great way to distribute binaries in an OS-agnostic way which does not depend on a package manager (e.g. no brew or apt-get).

This method is ideal for local development environments (which is how we use it) where you need the dependencies installed natively for your OS/architecture, such as installing a package on OSX.

See all available packages:

make -C install help

Install everything...

make -C install all

Install specific packages:

make -C install aws-vault chamber

Install to a specific folder:

make -C install aws-vault INSTALL_PATH=/usr/bin

Uninstall a specific package

make -C uninstall yq

Rebuilding GitHub Action Workflows

The GitHub Action workflows are compiled from the .github/package-template.yml file by running make -C .github workflows. It's also run automatically when rebuilding the README.md with make readme.

Run this make target anytime the package-template.yml changes or any new packages are added to the vendor/ folder.

IMPORTANT: The package-template.yml supports a single macro for interpolation %PACKAGE_NAME% which is replaced using a sed expression. Since the workflow uses a combation of gotemplate-like interpolations as well as inlines shell scripts, we used the %VAR% form of interpolation to avoid the need for endless escaping of interpolation specifiers.

Testing Locally

Alpine

$ make docker/build/apk/shell
$ make -C vendor/<package> apk

Debian

$ make docker/build/deb/shell
$ make -C vendor/<package> deb

RPM

$ make docker/build/rpm/shell
$ make -C vendor/<package> rpm

Mac

$ make -C vendor/<package> install

Examples

Docker Multi-stage Build

Add this to a Dockerfile to install packages using a multi-stage build process:

FROM cloudposse/packages:latest AS packages

COPY --from=packages /packages/bin/kubectl /usr/local/bin/

Docker with Git Clone

Or... add this to a Dockerfile to easily install packages on-demand:

RUN git clone --depth=1 -b main https://github.com/cloudposse/packages.git /packages && \
    rm -rf /packages/.git && \
    make -C /packages/install kubectl

Makefile Inclusion

Sometimes it's necessary to install some binary dependencies when building projects. For example, we frequently rely on gomplate or helm to build chart packages.

Here's a stub you can include into a Makefile to make it easier to install binary dependencies.

export PACKAGES_VERSION ?= main
export PACKAGES_PATH ?= packages/
export INSTALL_PATH ?= $(PACKAGES_PATH)/bin

## Install packages
packages/install:
        @if [ ! -d $(PACKAGES_PATH) ]; then \
          echo "Installing packages $(PACKAGES_VERSION)..."; \
          rm -rf $(PACKAGES_PATH); \
          git clone --depth=1 -b $(PACKAGES_VERSION) https://github.com/cloudposse/packages.git $(PACKAGES_PATH); \
          rm -rf $(PACKAGES_PATH)/.git; \
        fi

## Install package (e.g. helm, helmfile, kubectl)
packages/install/%: packages/install
        @make -C $(PACKAGES_PATH)/install $(subst packages/install/,,$@)

## Uninstall package (e.g. helm, helmfile, kubectl)
packages/uninstall/%:
        @make -C $(PACKAGES_PATH)/uninstall $(subst packages/uninstall/,,$@)

Contributing Additional Packages

In addition to following the Contributing section, the following steps can be used to add new packages for review (via a PR). If possible (and it usually is), you want to find an existing package with similarly packaged release (.tar, .gz, uncompressed binary, etc.), and copy and edit its Makefile.

1. Copy the Makefile from an existing, similar, package within the vendors directory. Name the new folder with the same name as the binary package being installed.
2. Edit the Makefile, ensuring the DOWNLOAD_URL is properly formatted
3. Run make init from within the directory to create the DESCRIPTION, LICENSE, RELEASE, and VERSION files.
4. En