Documentation

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
+### Update **make-deploy** submodule in your project
-
-    make create-docker-contexts
-    
-### 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.