From ec5e672d3cc8270331ee02ddd89e9b5577275538 Mon Sep 17 00:00:00 2001 From: Andreas Neue Date: Mon, 12 Jun 2023 17:09:46 +0200 Subject: [PATCH] Documentation --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 71 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 21739d6..314a824 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,13 @@ 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** 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. +**make-deploy** is licensed under the terms of the MIT-License. See [LICENSE](LICENSE) for info. ## Installation -Clone make-deploy as a submodule into your repository: +Clone **make-deploy** as a submodule into your repository: $ git submodule add https://git.chefkoch.net/pub/make-deploy @@ -36,23 +36,57 @@ 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 - -### Create docker contexts for the target hosts - make create-docker-contexts - -### Update make-deploy submodule in your project +### Update **make-deploy** submodule in your project make self-update ### Available options for DEPLOY_TYPE -copy, compose, swarm, k8s (TBD), helm, cron (TBD) +copy, compose, swarm, k8s, helm, cron, apt, systemd (tbd). #### copy @@ -66,6 +100,32 @@ Docker Compose deployment. Docker Swarm deployment. -##### k8s, helm, cron +##### k8s -To be implemented. +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.