Merge pull request #9 from uccser/readme-patch

Readme patch

README.md

@@ -1,12 +1,43 @@
 # Swarm Stack Updater
-The Swarm Stack Updater an automated tool built in shell that can be run periodically on a docker swarm to search for and identify any out of date stacks. If any changes are found, this tool automatically downloads, updates, and redeploys software back onto the swarm.
+The Swarm Stack Updater an automated tool built in shell that can be run periodically on a Docker Swarm to search for and identify any out of date stacks. If any changes are found, this tool automatically downloads, updates, and redeploys software back onto the swarm.
 
-This tool has been developed in conjuction with the University of Canterbury Computer Science Education Research Group as a University of Canterbury Sofware Engineering final year project. 
+This tool has been specifically engineered to find and update full Docker Stacks by downloading Docker Compose files from GitHub.
+This was after finding tools such as [Watchtower](https://github.com/containrrr/watchtower) or [Shepard](https://github.com/djmaze/shepherd) which only aimed to update individual Docker containers by updating images.
+Using Compose files means whole application stacks can be updated and can allow for configuration changes as well.  
 
-## How to use:
 
-### Deploying Using Docker
-* First create a config file matching this description:
+## Requirements
+* Can only be run in a Docker Swarm.
+* The tool makes use of the Github API and Container Registry.
+  You may have to update the script to work for other repositories and container registries.
+* Website must have a status url that returns a JSON object that contains both SHA-1 commit hash and a tag version.
+  ```
+  {"VERSION_NUMBER": "7.1.0", "GIT_SHA": "634d994d771fa23f65bc735bba32317ca71b374d"}
+  ```
+* Deployment requires [Swarm Cronjob](https://github.com/crazy-max/swarm-cronjob) running and deployed on the Swarm.
+* A secret is required for multiple GitHub requests (see the Compose file).
+  This must be named ```github_access_token```.
+  More about Docker Secrets can be found in the [Docker documentation](https://docs.docker.com/engine/swarm/secrets/).
+
+* The Docker images must contain additional information in their manifest files.
+  This is so the tool can identify whether a new image is available to download.
+
+* Manifest JSON should contain at least:
+```
+...
+labels: {
+  "org.opencontainers.image.revision": "<commit-sha>"
+}
+...
+```
+An [example is available within the CS Unplugged repository](https://github.com/uccser/cs-unplugged/blob/develop/infrastructure/production/django/Dockerfile#L28-L36).
+
+## Deployment:
+
+1. First create a config file so that the Swarm Stack Updater is able to recognise what it needs to update.
+  This should contain the stack's name, whether you are deploying the tool in a development environment, the websites url that you are updating as well as some repository information.
+
+This should look something like this:
 ```
 ---
 <stack-name>:
@@ -18,11 +49,24 @@ This tool has been developed in conjuction with the University of Canterbury Com
         user: <github_username>
 ```
 
-* Next save that config file as "swarm_updater_config" in your swarm, this can be done <br />
-by typing ```docker config create swarm_updater_config <path-to-file>```
+2. Next save that config file as "swarm_updater_config" and set it as a config file in your swarm, this can be done by typing the following command (or can be setup as part of step 3 in your deployment compose file). 
+```
+docker config create swarm_updater_config <path-to-file>
+```
+
 
+3. Deploy on your swarm swarm using Docker Compose. 
+* Make sure you include an env file if you need external varibles for deployment. 
+* To ensure that the tool can use docker commands add the volume ```/var/run/docker.sock:/var/run/docker.sock``` to give the tool access to the Docker daemon.
+* In order to configure [Swarm Cronjob](https://github.com/crazy-max/swarm-cronjob) Docker Labels are used. In the following the tool has been setup to run every 2 mins and will not re run if already running.
+```
+ labels:
+          - "swarm.cronjob.enable=true"
+          - "swarm.cronjob.schedule=*/2 * * * *" # Testing Update Every Minute
+          - "swarm.cronjob.skip-running=true"
+```
 
-* Finally Deploy on swarm using docker compose:
+An example of a full compose file to setup the Swarm Stack Updater can be seen below:
 ```
 version: '3.8'
 
@@ -58,44 +102,33 @@ secrets:
         external: true
 ```
 
+## Development
+
 ### Running Locally
 
 The tool has been designed specifically to run using docker swarm or compose but it can be run locally if required. I have tryed my best to remove all issues when running locally but it may not be perfect.
 
-* First Clone the repository using following the command:
+1. Clone the repository using following the command:
 ```
 https://github.com/uccser/swarm-stack-updater.git
 ```
-* Then use the following command to pull BATS, which is used for automated testing:
+2. Use the following command to pull BATS, which is used for automated testing.
+  This will pull all the required tools for running and creating tests for this application.
 ```
 git submodule update --init
 ```
-This will pull all the required tools for running and creating tests for this application.
-
+3. Ensure that you have a configuration file created and have the requried environment varibles defined. To define environment varibles use the command ```export ENV_VAR=<value>```.
 
-
-## Requirements
-* The tool makes use of the github api and container registry. You may have to update the script to work for other 
-repositories and container registries.
-* Website must have a status url that returns a JSON object that contains both 
-sha commit hash and a tag version.
-* ```{"VERSION_NUMBER": "3.10.0", "GIT_SHA": "a49a111d"}```
-* Deployment on swarm requires swarm cronjob running and deployed on swarm
-this can be found here https://github.com/crazy-max/swarm-cronjob
-* From the bottom of the compose file you can see that a secret is required. This should be a github_access_token to allow for multiple requests. More about
-docker secrets can be found here: https://docs.docker.com/engine/swarm/secrets/
-* Your docker images should also contain some extra information in their manifest files. This is so the app is able to identify whether a new image is available to download.
-
-Manifest JSON should contain at least:
+4. Run the swarm updater by running the command 
 ```
-...
-labels: {
-  "org.opencontainers.image.revision": "<commit-sha>"
-}
-...
+./src/swarm_stack_updater.sh
+```
+You may need to set to to be executible this can be done by typing the command 
+```
+chmod +x /src/swarm_stack_updater.sh
 ```
 
-## Testing
+### Testing
 BATS Core is being used to test some of the swarm stack updaters functions. This hopefully ensures that main functionailly of the application is kept consistant as updates and changes are preformed to the tool. 
 
 ### Running Tests