make-deploy/README.md

# make-deploy

A simple Makefile based deployment system.

**make-deploy** was initially hosted at https://git.dnix.de/an/make-deploy. Since it has become heavily used at chefkoch.de for system deployments, and lots of code is committed there, we moved the repo to https://git.chefkoch.net/pub/make-deploy. A mirror still exists at https://git.dnix.de/mirror/make-deploy.

**make-deploy** is licensed under the terms of the MIT-License. See [LICENSE](LICENSE) for info.

## Installation

1. Clone **make-deploy** as a submodule into your repository:

    $ git submodule add https://git.chefkoch.net/pub/make-deploy
    
2. Create a symlink to the Makefile:

	$ ln -s make-deploy/Makefile .
	
3. Create `config.mk` (for common config options) and `secrets.mk` (for sensitive information, should be git-crypted) in your project.

Example `config.mk`:

    DEPLOY_NAME = my-project
	DEPLOY_PATH = /srv
	DEPLOY_TYPE = compose
	DEPLOY_HOSTS = server01.example.com server02.example.com

	DOCKER_IMAGE = dr.example.com/my-project:latest
	DOCKER_LOGIN = 1
	DOCKER_REGISTRY = dr.example.com

	SSH_USER = ci

Example `secrets.mk`:

    DOCKER_USER = root
    DOCKER_PASS = secret1234

By setting `DEPLOY_CONFIG_OVERRIDE`, an alternative config can be loaded to override existing configuration settings. This is useful in script calling make deploy or in a `.gitlab-ci.yml` in order to control settings for different targets.

## Usage

### Philosophy

**make-deploy** lets you deploy software on the commandline with make.

Doing as much config as you can in `config.mk`, via `DEPLOY_OVERRIDE_CONFIG` and in `secrets.mk` will keep this ability intact without depending on complex build systems (e.g. Gitlab deployments controlled by .gitlab-ci.yml and other stuff like that). OTOH it does not stop you from doing this: simply call `make deploy` in your build pipeline in order to get the best of both worlds.

Relying only on GNU Make and simple CLI tools makes deployments robust and still possible, when big parts of your infrastructure are broken and have to be redeployed.

### Working principle

**make-deploy** calls several stages in the deployment process, which are `mandatory prepare build test upload pre-deploy pre-local pull start post-local post-deploy reload`.

`mandatory`: Checks if all needed variables are set in config.mk.

`prepare`: Creates needed directory for the deployment on the target system, sets secure file permissions for `secrets.mk`.

`build`: Calls `build.sh` locally. This is for building purposts, e.g. docker build and push.

`test`: Calls `test.sh` locally,

`upload`: rsyncs the contents of the repo to the target systems.

`pre-deploy`: Runs `pre-deploy.sh` remotely on the target hosts. Used for service specific purposes.

`pre-local`: Runs `pre-local.sh` locally. Used for service specific purposes.

`pull`: Pulls docker images (if appropriate).

`start`: Starts the service.

`post-local`: Runs `post-local.sh` locally. Used for service specific purposes.

`post-deploy`: Runs `post-deploy.sh` remotely on the target hosts. Used for service specific purposes.

`reload`: Runs `reload.sh` remotely on the target hosts.  Used for service specific reloading/restarting.

### Start the deployment process

    make deploy

### Update **make-deploy** submodule in your project

    make self-update

### Available options for DEPLOY_TYPE

#### simple

Just copy the repo to the remote location(s). Put additional logic into build.sh, start.sh, pre-deploy.sh, and post-deploy.sh.

#### compose

Docker Compose deployment.

##### swarm

Docker Swarm deployment.

##### k8s

K8S deployment.

`K8S_CONTEXT`: K8S context to be used. Make sure to properly set up your K8S credentials (kube config) and provide a local copy of kubectl.

##### helm

K8S deployment via helm.

`K8S_CONTEXT`: K8S context to be used. Make sure to properly set up your K8S credentials (kube config) and provide a local copy of kubectl.

`NAMESPACE`: K8S namespace. TODO: This will be renamed to K8S_NAMESPACE in the future.

`HELM_VALUES_FILE`: Contains the specific variables for this deployment.

`HELM_CHART_NAME`: Name of the helm chart.

`HELM_CHART_PATH`: Path of the helm chart.

The helm deployment processes the contents of `HELM_VALUES_FILE` with envsubst and pipes the result to `helm upgrade` to deploy the application.

##### cron

Deploy cronjob.

##### systemd

systemd. (TBD)

##### apt

APT deployment on debian-like distributions.