mach

README

Mach

Website | Discussions | Documentation | Twitter | Installation Guide | Contribution Guide

Mach is a cli application for using docker to quickly and easily manage infrastructure and services through code.

Mach provides tooling around a simple docker and docker-machine based workflow for managing infrastructure, services and docker images. This allows you to easily leverage any git repository for the purposes of managing your Infrastructure as Code.

This project is written in golang, using cobra. Check the wiki for additional documentation and user guides.

Usage

This tool runs in git repos thats meant to represent an IaC implementation. The git repo can store docker images, these are used to populate a registry and to as services for docker compositions. The repo can also store docker compositions (or stacks), which can be used to deploy to docker-machines. Mach can also be used to transfer docker-machine certificates to and from S3.

mach build # builds every image in working directory (add .mach.yaml to configure)
mach build example # builds every image in `example` directory
mach build example:template # builds `Dockerfile-template[.tpl]` in `example` directory 
mach compose up # runs `docker-compose up` against every composition in working directory (add .mach.yaml to configure)
mach compose <service> up # runs `docker-compose up` against composition that matches the service
mach machine restore example-restore # downloads machine from S3 and installs to ~/.docker/machine
mach machine backup example-machine # copies machine configuration and certs to S3

Building Docker Images

Maintain a collection of docker images that can be rapidly built and pushed to a registry. Dockerfiles can be made using templates supporting includes, conditionals, loops, etc. mach build can build these images, and tag them based on git branch and filename conventions. This allows for maintaining a mainline image for public use, and versions for test.

Managing Docker Machines

Mach can be used to backup docker-machine certificates and configurations to Amazon S3 buckets. This makes sharing docker-machine credentials with teammates (and pipelines) simple.

AWS authentication is performed through the golang library, which provides a variety of ways to authenticate. You can use a tool like aws-vault, ~/.aws/credentials files or environment variables such as:

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_DEFAULT_REGION=us-west-2

Managing Docker Compositions

This tool also provides a thin wrapper around the docker-compose command, and will process docker-compose.yml.tpl files before passing them to compose. The compose command can run against any one composition, or against all of them in sequence to allow for managing everything in one command.

Installation

Binaries are compiled with every release, you can grab it from the releases page, and use it as-is. These files are fit to be ran directly, from $PATH, or even committed i.e. /path/to/iac-repo/bin/mach and invoked with cd /path/to/iac-repo/ && bin/mach.

Homebrew

Installing with brew is the preferred way to install for most use-cases. Homebrew installs the tool globally, and is updated with every release.

brew tap superterran/mach
brew install mach

Compiling From Source

If you prefer to compile from source, the Makefile can be used:

git clone git@github.com:superterran/mach.git 
cd mach
make install # runs `go build .` and copies to /usr/local/bin

Contributing

For a complete guide to contributing to Mach, see the Contribution Guide

Bug reports and pull requests are welcome on GitHub at https://github.com/superterran/mach/issues.

License

Mach is released under the MIT License

Author Information

This project was started in 2021 by Doug Hatcher superterran@gmail.com.

Documentation

Overview

Mach is a cli application for using docker to quickly and easily manage infrastructure and services through code.

Mach provides tooling around a simple docker and docker-machine based workflow for managing infrastructure, services and docker images. This allows you to easily leverage any git repository for the purposes of managing your Infrastructure as Code.