README.yaml

name: Packages 

description: |-
  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](https://github.com/cloudposse/packages/issues) or submit a PR (*preferred*). We'll review quickly!

# License of this project
license: "APACHE2"

# Canonical GitHub repo 
github_repo: cloudposse/packages

# Badges to display
badges:
  - name: "TravisCI Build Status"
    image: "https://travis-ci.org/cloudposse/packages.svg?branch=master"
    url: "https://travis-ci.org/cloudposse/packages"
  - name: "Codefresh Build Status"
    image: "https://g.codefresh.io/api/badges/build?repoOwner=cloudposse&repoName=packages&branch=master&pipelineName=packages&accountName=cloudposse&type=cf-1"
    url: "https://g.codefresh.io/repositories/cloudposse/packages/builds?filter=trigger:build;branch:master;service:5b234974667ab79287990636~packages"
  - name: "Latest Release"
    image: "https://img.shields.io/github/release/cloudposse/packages.svg"
    url: "https://github.com/cloudposse/packages/releases/latest"
  - name: "Slack Community"
    image: "https://slack.cloudposse.com/badge.svg"
    url: "https://slack.cloudposse.com"

related:
  - name: "build-harness"
    description: "Collection of Makefiles to facilitate building Golang projects, Dockerfiles, Helm charts, and more"
    url: "https://github.com/cloudposse/build-harness"
  - name: "geodesic"
    description: "Geodesic is the fastest way to get up and running with a rock solid, production grade cloud platform built on strictly Open Source tools."
    url: "https://github.com/cloudposse/geodesic"

# Other files to include in this README from the project folder
include:
  - "docs/targets.md"

usage: |-

  ### Alpine Repository (recommended)
  
  A public Alpine repository is provided by [Cloud Posse](https://cloudposse.com). The repository is hosted on Amazon S3 and fronted by [CloudFlare's CDN](http://cloudflare.com) with end-to-end TLS. This ensures insane availability with DDoS mitigation and low-cost hosting. Using this alpine repository is ultimately more reliable than depending on [GitHub for availability](https://twitter.com/githubstatus) and provides an easier way to manage dependencies pinned at multiple versions. 
  
  The repository itself is managed using [`alpinist`](https://github.com/cloudposse/alpinist), which takes care of the heavy lifting of building repository indexes. You can self-host your own Alpine repository using this strategy.
  
  ### Configure the alpine repository:

  #### The Easy Way

  We provide a bootstrap script to configure the alpine repository for your version of alpine. 

  ```
  curl -sSL https://apk.cloudposse.com/install.sh | sh
  ```
  __NOTE__: Requires `bash` and `curl` to run:

  #### For Docker
  
  Add the following to your `Dockerfile` near the top.
  ```
  # Install the cloudposse alpine repository
  ADD https://apk.cloudposse.com/ops@cloudposse.com.rsa.pub /etc/apk/keys/
  RUN echo "@cloudposse https://apk.cloudposse.com/3.8/vendor" >> /etc/apk/repositories
  ```
  __NOTE__: we support alpine `3.7` and `3.8` packages at this time

  ### 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 gomplate
  ```

  But we recommend that you use version pinning:
  ```
  apk add gomplate==3.0.0-r0
  ```

  And maybe even repository pinning, so you know that you get our versions:
  ```
  apk add gomplate@cloudposse==3.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](https://docs.cloudposse.com/local-dev-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
  ```

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 master 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 ?= master
  export PACKAGES_PATH ?= packages/
  export INSTALL_PATH ?= $(PACKAGES_PATH)/vendor

  ## 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/,,$@)
  ```


# Contributors to this project
contributors:
  - name: "Erik Osterman"
    github: "osterman"
  - name: "Igor Rodionov"
    github: "goruha"
  - name: "Andriy Knysh"
    github: "aknysh"