Merge pull request #5 from mabruraas/develop

Release 0.1

Author: Magnus Brurås

.gitignore

@@ -1,6 +1,9 @@
 .idea
 *.iml
 
+web/node_modules
+web/package-lock.json
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Dockerfile

@@ -0,0 +1,35 @@
+FROM            node:lts-alpine
+
+ENV             DW_HOME /opt/dockwatch
+
+
+#               Python
+WORKDIR         ${DW_HOME}/api
+COPY            ./api .
+
+RUN             apk update \
+                  && apk add \
+                    --no-cache \
+                    python3 \
+                  && python3 -m ensurepip \
+                  && rm -r /usr/lib/python*/ensurepip
+
+RUN             pip3 install \
+                  flask-cors \
+                  docker \
+                  Flask \
+                && rm -r /root/.cache
+
+
+#               Yarn/NPM
+WORKDIR         ${DW_HOME}/web
+COPY            ./web .
+RUN             yarn install \
+                  && yarn --prod build \
+                  && npm install -g react-scripts \
+                  && react-scripts build
+
+
+EXPOSE          1609
+WORKDIR         ${DW_HOME}
+CMD             [ "python3", "api/app.py" ]

README.md

@@ -1,174 +1,141 @@
 # DockWatch
-A system for listing out your deployed containers on a specific node.
-Should be running on the specific node.
+An application for listing out your deployed containers on a specific node.
 
 ## Why DockWatch
 We do all have a full CI/CD setup, so what more do we need?
 
-Since we've might have enabled the possibility
-(_we do this in the **Example Setup** below_) to deploy from every
-branch of each repository - it's necessary to keep track of
-what is running on the nodes in each environment.
+Since we've might have enabled the possibility to deploy code from
+every branch in each of the repositories - it's necessary to keep
+track of what is running on all the nodes in each environment.
 
-With the DockWatch API running on each of the nodes,
-the DockWatch Web can list out each version of each application deployed.
+With the DockWatch running on each of the nodes in an environment, it's
+possible to get an overview of all running containers on each node.
 
-Through the Web component it will be possible to delete specific containers,
-when you feel to clean up earlier mess.
+Through the UI it will be possible to interact with specific containers,
+like delete, restart or access logs. Main focus should be to clean
+up earlier deployments, of feature branches that is not relevant anymore.
 
-### DockWatch pair
-The API does not necessarily need to be exposed outside the node,
-if you deploy the API and the Web containers side-by-side on each node.
-This will let you access a specific node and watch and/or clean up old deployments.
+~~It is possible to configure each DockWatch to access
+the other APIs of the other DockWatch instances.
+This is done runtime, by adding a new Node with name,
+API URL and other grouping tags~~
+_Currently not implemented, WIP_
 
-### Central DockWatch Web
-Instead of having multiple access points for watching your deployments,
-it's possible to deploy one single instance of DockWatch Web and
-applying DockWatch API references in the Web UI.
 
+# Technology
+DockWatch mainly consist of two components; **API** and **Web**.
 
-# Components
-System consist of two components, API and Web.
+Both systems are bundled, where a Python Flask instance serves a React
+frontend, as well as an API for interaction with the Docker engine.
 
-### API
-Python Flask service for querying the docker engine.
-The API will return information about which images has deployed
-containers, what versions of each image that has containers,
-and the state of the containers.
+~~̃It's not necessary to take use of the Web component for each node.
+Because of the possibility to add other API URLs runtime~~
 
-The API should always be running on the respective node.
+## API
+The API is a Python Flask service for querying the docker engine,
+on the node where it's deployed. It will return information about
+all running containers, which image they are created of,
+including version tags, and labels for both image and container.
 
 ### Web
-DockWatch Web is a frontend for presenting the deployed containers
-on one or multiple nodes.
-
-The Web component should either be a central service,
-connected towards each API, or a single instance for each API deployed.
+The Web component is a React JS system, served as static files,
+from the Flask server. It's responsible for presenting the API data
+from one ~~or multiple~~ node~~s~~.
 
 
 # Usage
 
-## Build
+## Getting started
+To just run the system, use the following command. Note that the `/var/run/docker.sock`
+always should be mounted, to actually access the local docker engine.
 ```bash
-docker build -t mabruras/dock-watch-api
-docker build -t mabruras/dock-watch-web
+docker run -v /var/run/docker.sock:/var/run/docker.sock mabruras/dockwatch
 ```
 
-## Deploy
+It's recommended to run DockWatch with the `hidden`-label,
+to avoid it discovering itself, and not being able shut it down through itself.
+Make also sure to export the `1609`-port where the application is running.
 ```bash
 docker run -d \
-  -p 5000:5000 \
+  -p 1609:1609 \
+  -l "dockwatch.hidden=True" \
   -v /var/run/docker.sock:/var/run/docker.sock \
-  mabruras/dock-watch-api
-
-docker run -d \
-  -p 3000:3000 \
-  mabruras/dock-watch-web
+  mabruras/dockwatch
 ```
 
-## Example setup
-
-### Prerequisites
-* SCM (eg. Git w/`Github`)
-* CI-tool (eg. `Concourse`)
-* CD-tool (eg. `Rundeck`)
-* Proxy (eg. `Traefik`)
-* DockWatch
-
-### Flow
-#### SCM
-(_Source Control Management_)
-
-Make commits to the SCM, independent of branch,
-trigger the CI-tool through use of git-hooks.
 
-#### CI
-(_Continuous Integration_)
+## Standalone Applications
+It is possible to deploy either of the components (API and Web) standalone,
+even though it's recommended to always be deployed as a complete system.
 
-Let the CI-tool Build/compile,
-or what ever the application/system requires,
-before it wraps the application up in a Docker image.
 
-For best result, let the docker image tags be on the following syntax:
-`${DCKR_REG}/${APP_NAME}:${BRANCH_NAME}`.
-
-Based on the following details (personal preference): 
-* Application name: `Awesome App`
-* Registry url: `registry.example.com`
-* Issue tracker reference: `AA-123`
-* Branch name: `feature/AA-123`
-
-It's possible to create a setup like this:
+### Deploy
+You can deploy a single instance of the API, which is
+useful when planning to use a centralized DockWatch Web instance.
 ```bash
-DCKR_REG="registry.example.com"                     # Could be stored in the CI-tool
-APP_NAME="awesome-app"                              # Defined by the pipeline
-GIT_BRANCH="feature/aa-123_implement-stuff"         # Should be fetched from either SCM or CI-tool
-VERSION=$(echo ${GIT_BRANCH##origin/} | tr "/_" -)  # Replace / and _ with -, also remove "origin/"
-                                                    # from the branch name (optional)
-docker build -t ${DCKR_REG}/${APP_NAME}:${VERSION} ${PWD}
-
-# Resulting in:
-# registry.example.com/awesome-app:feature-aa-123-implement-stuff
-```
+docker build -t mabruras/dockwatch-api api
 
-Add desired labels when building the Docker image.
-(All labels will be available through the API)
-
-Example labels:
-* `branch=${GIT_BRANCH}`
-* `app_name=${APP_NAME}`
-* `version=${VERSION}`
-
-_**TIP:** There could be a parameterized hook to
-auto trigger deployment to development environments_
+docker run -d \
+  -p 1609:1609 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  mabruras/dockwatch-api
+```
 
-#### CD
-(_Continuous Deployment_)
+If there is deployed multiple singular APIs in the environment,
+it might be useful to only deploy a singular Web instance, without any connected API.
+When deploying a singular Web component,
+make note of the `REACT_APP_API_URL` to override the default API URL.
+~~There is also possible to manually add multiple other API references through the UI.~~
+```bash
+docker build -t mabruras/dockwatch-web web
 
-After building the Docker image, push it to the registry,
-and the CI-tool should take over.
+docker run -d \
+  -p 3000:3000 \
+  -e "REACT_APP_API_URL=http://localhost:1609/api" \
+  mabruras/dockwatch-web
+```
 
-`Rundeck` makes it possible to access one or more nodes,
-where it can be executed commands.
-Parameters should be:
-* `Application`
-* `Version`
-* `Environment` # Used to decide what nodes to access
-* `Registry` # If you have multiple Docker Registries
+### Environment Variables
+Currently there isn't implemented use of a configuration file,
+but options are available through environment variables.
+Make sure that your deployment includes the necessary values by modifying these.
 
-Example:
-```bash
-IMG_REF="${REGISTRY}/${APPLICATION}:${VERSION}"
+| VARIABLE | EXAMPLE | DESCRIPTION |
+| :------: | :-----: | :---------: |
+| DW_PORT | 8080 | What port DownWatch is running on (_default: 1609_) |
+| REACT_APP_API_URL | http://localhost:1609/api | URL for where to access the DockWatch API |
+| REACT_APP_URL_LBL | app.url | What label referring to the applications URL (_default: container.url_) |
 
-docker run -d \
-  --name "${APPLICATION}-${VERSION}" \
-  ${IMG_REF}
-``` 
 
-In this case, the `"${APPLICATION}-${VERSION}"` is representing the sub-domain,
-dependent on the Traefik configuration.
-So make sure `"${APPLICATION}-${VERSION}"` is "URL-friendly".
+### Internal Labels
+Internal labels are those who DockWatch uses for execute extra,
+custom or special logic, when detecting on a container.
 
-When deploying, remember to include all necessary environment labels.
-Each label you add, will be available through the DockWatch API,
-and will let you modify the frontend based upon the labels.
+#### Hidden containers
+It's not everything that should be exposed to the users,
+that's why a container can be hidden from DockWatch.
+Services like DockWatch should by default be hidden,
+and could be labeled with `dockwatch.hidden=true` to achieve this.
 
-Example labels:
-* `environment=dev` # _Should be changed to actual environment_
-* `url=app1.dev.example.com` # _Dependent on Traefik setup,
-container name (`app1` in this case) could represent the sub domain_
 
-#### Proxy
-With `TræfIk`/traefik, you'll be able to auto detect
-your Docker containers, and create routes to each container.
+### Docker Compose
+Instead of running each and every one of the components manually,
+there is created Docker Compose files for handling this.
+These files already are preconfigured with the recommended
+labels and environment variables.
 
-So optimal, the earlier example will result in the following accessible URL:
-`https://awesome-app-feature-aa-123-implement-stuff.dev.example.com`
+```bash
+docker-compose -f files/docker-compose.yml build
+docker-compose -f files/docker-compose.yml up -d
+```
 
-#### DockWatch
-DockWatch API will be running on each of the nodes,
-with a DockWatch Web container at it's side.
+##### Override default environment variable
+It's important to notice that the docker-compose file contains a
+default to what API the Web instance is connecting towards; localhost.
+To override the APIs default URL, you can set the `DOCK_WATCH_API`
+environment variable being the address to the node running the API.
 
-The DockWatch Web is exposed through Traefik 
-(`--label "traefik.frontend.rule='Host: dw.dev.example.com'"`)
-to easily access the DockWatch panel.
+```bash
+export DOCKWATCH_API="http://api.example.com"
+docker-compose -f files/docker-compose.yml up -d
+```

api/Dockerfile

@@ -2,15 +2,16 @@ FROM            python:3.7
 
 MAINTAINER      Brurås, Magnus <mabruraas@gmail.com>
 
-ENV             WRK_DIR /opt/dockwatch
+ENV             WRK_DIR /opt/dockwatch-api
 
 RUN             pip3 install \
-                docker \
-                Flask
+                  flask-cors \
+                  docker \
+                  Flask
 
-COPY            ./* ${WRK_DIR}
+COPY            ./* ${WRK_DIR}/
 
 WORKDIR         ${WRK_DIR}
-EXPOSE          5000
+EXPOSE          1609
 
 CMD             [ "python", "app.py" ]