Merge pull request #9 from mabruras/develop

Develop into Master

Author: mabruras

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,py}]
+charset = utf-8
+
+# 4 space indentation
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.js]
+indent_style = space
+indent_size = 2
+
+[package.json]
+indent_style = space
+indent_size = 2

Dockerfile

@@ -1,35 +1,27 @@
-FROM            node:lts-alpine
+FROM            node:lts-alpine as node-build
 
-ENV             DW_HOME /opt/dockwatch
+WORKDIR         /usr/src/app
+COPY            ./web /usr/src/app
+RUN             yarn install \
+                  && yarn --prod build \
+                  && npm install -g react-scripts \
+                  && react-scripts build
 
+FROM            python:3.7
+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
+COPY            --from=node-build /usr/src/app/build ${DW_HOME}/web
 
 RUN             pip3 install \
                   flask-cors \
+                  pycrypto \
                   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" ]
+

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Magnus Brurås
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,46 +1,30 @@
 # DockWatch
-An application for listing out your deployed containers on a specific node.
+[![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENCE)
+[![](https://img.shields.io/docker/automated/mabruras/dockwatch.svg)](https://hub.docker.com/r/mabruras/dockwatch 'DockerHub')
+[![](https://img.shields.io/docker/stars/mabruras/dockwatch.svg)](https://hub.docker.com/r/mabruras/dockwatch 'DockerHub')
+[![](https://img.shields.io/docker/pulls/mabruras/dockwatch.svg)](https://hub.docker.com/r/mabruras/dockwatch 'DockerHub')
 
-## Why DockWatch
-We do all have a full CI/CD setup, so what more do we need?
+Application for listing deployed applications in a single- or multi-node 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.
+## What is DockWatch
+DockWatch is a system for accessing an overview of
+all deployed Docker containers in an environment.
 
-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.
+By restricting which containers being visible and possible to interact with,
+it's easy to let the developers manage the environments on their own.
 
-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.
+As a contribution to a feature-branch deployment system, DockWatch will let
+the developers see what versions of each application, is currently deployed.
+It is possible to remove, restart and watch the logs of the containers.
 
-~~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_
+DockWatch wants to highlight the importance of developer contribution towards the
+application environments, by letting them take part in the deployment processes.
 
+## Overview
+When deploying multiple branches of each applications,
+it's useful to get them grouped by the application name.
 
-# Technology
-DockWatch mainly 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.
-
-~~̃It's not necessary to take use of the Web component for each node.
-Because of the possibility to add other API URLs runtime~~
-
-## 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
-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~~.
+![Overview of deployments in DockWatch](./files/images/dockwatch_images.png 'Images Overview')
 
 
 # Usage
@@ -52,90 +36,135 @@ always should be mounted, to actually access the local docker engine.
 docker run -v /var/run/docker.sock:/var/run/docker.sock mabruras/dockwatch
 ```
 
-It's recommended to run DockWatch with the `hidden`-label,
-to avoid it discovering itself, and not being able shut it down through itself.
+It's recommended to run DockWatch with the `hidden`-label, to avoid it discovering itself,
+and denying users interacting with it's running state through the UI.
+Alternatively the `restartable`- and `removable`-labels can be used.
 Make also sure to export the `1609`-port where the application is running.
 ```bash
 docker run -d \
   -p 1609:1609 \
-  -l "dockwatch.hidden=True" \
+  -l "dockwatch.hidden=true" \
   -v /var/run/docker.sock:/var/run/docker.sock \
   mabruras/dockwatch
 ```
 
+### Multiple Nodes
+To start it with synchronization across multiple nodes, the following should be a minimum.
 
-## 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.
-
-
-### Deploy
-You can deploy a single instance of the API, which is
-useful when planning to use a centralized DockWatch Web instance.
 ```bash
-docker build -t mabruras/dockwatch-api api
-
 docker run -d \
-  -p 1609:1609 \
+  --net host \
+  -l "dockwatch.hidden=true" \
+  -e "DW_GROUP=dev" \
+  -e "DW_MODE=multi" \
+  -e "DW_SECRET=mySecret" \
   -v /var/run/docker.sock:/var/run/docker.sock \
-  mabruras/dockwatch-api
+  mabruras/dockwatch
 ```
+**[!]** Remember that `DW_SECRET` should be the same to all instances in the same `DW_GROUP`!
 
-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
 
-docker run -d \
-  -p 3000:3000 \
-  -e "REACT_APP_API_URL=http://localhost:1609/api" \
-  mabruras/dockwatch-web
-```
-
-### Environment Variables
+## 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.
+Make sure that your deployment includes the necessary values by modifying these environment variables.
+
+### General
+| VARIABLE | EXAMPLE | DESCRIPTION | DEFAULT |
+| :------- | :-----: | :---------- | :-----: |
+| `WRK_DIR`| /opt/dockwatch | Directory where dockwatch is located | current directory/`.` |
+| `DW_PORT`| 8080 | What port DownWatch is running on | 1609 |
+| `DW_MODE`| multi | `single` if DockWatch is a single instance, `multi` enables "Multiple Nodes" | single |
+| `DW_LOG_THRESHOLD` | 120 | **Seconds** to hold each log stream open | 300 |
+
+**[!]** Be careful with `DW_LOG_THRESHOLD`.
+This value tells when to close a log stream, after accessing
+a detailed page for a container, where the log is streamed.
+Since closing the page will not close the open log stream server side,
+there is implemented a timeout for the stream.
+Hopefully this will be changed with a better solution down the road.
+
+### Multiple Nodes
+Some environment variables does only make sense to use in Multi mode,
+due the configuration of synchronization is superfluous when not using it.
+
+| VARIABLE | EXAMPLE | DESCRIPTION | DEFAULT |
+| :------- | :-----: | :---------- | :-----: |
+| `DW_GROUP` | Development | Grouping of DockWatch instances, to pick up broadcasts from only within the group | dw_default |
+| `DW_SECRET` | 53cr37-p455w0rd | Broadcast message encryption, must be equal within `DW_GROUP` |  |
+| `DW_BROADCAST_PORT` | 12345 | Select port to send/receive broadcast messages through | 11609 |
+| `DW_BROADCAST_INTERVAL` | 5 | Time delay in minutes between broadcasts | 30 |
+| `DW_NET_MASK` | 255.255.0.0 | Network mask for your subnet, is used to determine broadcast address | 255.255.255.0 |
+
+
+## Internal Labels
+Internal labels are those who DockWatch uses for execute extra,
+custom or special logic, when detecting on a container.
 
-| 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_) |
+| LABEL | DESCRIPTION | VALUE |
+| :---: | :---------: | :---: |
+| dockwatch.hidden | Marks the container as hidden, and unavailable through DockWatch Web | `true` or `false` |
+| dockwatch.restartable | Enable or disable the posibility to **restart** the container | `true` or `false` |
+| dockwatch.removable | Enable or disable the possibility to **remove/delete** the container | `true` or `false` |
+| dockwatch.url | URL for accessing the application running in the container | _custom_ |
 
+### Hidden
+It's not everything that should be exposed to the users, that's why a container could be hidden from DockWatch.
+It's recommended that services like DockWatch should be hidden by default.
 
-### Internal Labels
-Internal labels are those who DockWatch uses for execute extra,
-custom or special logic, when detecting on a container.
+### Restartable
+Users are able to restart containers with this flag.
+Do not use this label on containers that should not be restarted by the users.
 
-#### 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.
+### Removable
+Users are able to remove containers with this flag.
+The action of removing a container is not revertible - don't let users remove your critical containers.
 
+### Container URL
+Enabled link to the deployed version of the application.
+Recommended to be included, for usability and accessibility for the developer and/or users.
 
-### 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.
 
-```bash
-docker-compose -f files/docker-compose.yml build
-docker-compose -f files/docker-compose.yml up -d
-```
+# Technology
+DockWatch mainly consist of two components; **API** and **Web**.
 
-##### 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.
+Both systems are bundled, where a Python Flask backend serves a React
+frontend, as well as an API for interaction with the Docker engine.
 
-```bash
-export DOCKWATCH_API="http://api.example.com"
-docker-compose -f files/docker-compose.yml up -d
-```
+## API
+The API is a Python Flask service for querying the Docker engine,
+on the node where it's deployed, as well as other nodes - if available.
+It will return information about all running containers,
+which image they are created of (including version tags),
+and labels for both image and container, for each node available.
+
+## Web
+The Web component is created on the React JS framework, served as static files,
+from the Flask server. It's responsible for presenting the API data from each node.
+
+
+# Multiple Nodes
+By running DockWatch with `--net=host`, it is able to
+automatically synchronize between instances within the same subnet.
+
+They will share their own IP address, along with all other known IP addresses
+from earlier broadcasts. Each broadcast will reach out to the other instances
+to increase the possibility of each node knowing about each other.
+
+When a user interacts with a container, the instance contacted will reach
+out to all known DockWatch instances to perform the same action on each node.
+
+It could be hard to read logs on multiple instances, so DockWatch
+solves this by letting the user select each node separately.
+
+DockWatch connects to other instances by broadcasting it's own position,
+triggering all listening instances to do the same.
+Each broadcast received is used to update its own configuration to keep
+track of where each instance is running.
+
+By regularly broadcasting the positions, it increases the chance of detecting
+each other and keep up to date each API reference.
+
+When interacting with a instance, it will start a sequence of similar API
+calls to the rest of the instances. This lets the user known the status of
+each instance.