Merge pull request #33 from python-microservices/feature/docs

Documentation

Author: avara1986

AUTHORS

@@ -1,3 +1,5 @@
 Alberto Vara <[email protected]>
 Hugo Camino <[email protected]>
 José Manuel <[email protected]>
+Javier Luna molina <[email protected]>
+pilamb <[email protected]>

README.md

@@ -9,6 +9,10 @@
 [![Total alerts](https://img.shields.io/lgtm/alerts/g/python-microservices/pyms.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/python-microservices/pyms/alerts/)
 [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/python-microservices/pyms.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/python-microservices/pyms/context:python)
 
+PyMS, Python MicroService, is a collections of libraries, best practices and recommended ways to build 
+microservices with Python.
+
+To know how use, install or build a porject see the docs (TODO: add url to readthedocs)
 
 ## Installation 
 ```bash
@@ -81,3 +85,20 @@ pipenv install --deploy
 ```bash
 pipenv shell
 ```
+
+## Documentation
+
+This project use MkDocs
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs help` - Print this help message.
+
+### Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
+

docs/configuration.md

@@ -0,0 +1,93 @@
+# Configuration
+
+Each microservice needs a config file in yaml or json format to work with it. This configuration contains
+the Flask settings of your project and the [Services](services.md).
+
+a simple configuration file could be a config.yaml:
+
+```yaml
+pyms:
+  requests: true
+  swagger:
+    path: ""
+    file: "swagger.yaml"
+my-ms:
+  DEBUG: true
+  TESTING: false
+  APP_NAME: "Python Microservice"
+  APPLICATION_ROOT: ""
+```
+
+or in a config.json:
+
+```json
+{
+"pyms":{
+  "requests": true,
+  "swagger": {
+    "path": "",
+    "file": "swagger.yaml"
+    }
+  },
+"my-ms": {
+  "DEBUG": true,
+  "TESTIN": false,
+  "APP_NAME": "Python Microservice",
+  "APPLICATION_ROOT": ""
+  }
+}
+```
+
+This file could contains this keywords:
+
+
+## pyms block
+
+```pyms```: all subsets inside this keyword are the settings of this library. Each keyword will be a service of our
+[Microservice class](ms_class.md). For example, we declare our microservice class as:
+
+```python
+from pyms.flask.app import Microservice
+ms = Microservice(service="my-ms", path=__file__)
+```
+and a `config.yaml` file:
+
+```yaml
+pyms:
+  requests: true
+```
+
+our object `ms` has an attribute `requests` that is a instance of our service [requests](services.md). 
+
+## Our microservice block
+This part contains all keywords of a [Flask Configuration Handling](http://flask.pocoo.org/docs/1.0/config/) and our 
+constants of the enviroments (local configuration, staging configuration...). Keep in mind that a Flask configuration needs
+the keywords to be declared as uppercase.
+
+The name of this block is defined when you create the object of [Microservice class](ms_class.md):
+
+### Example 1
+```python
+from pyms.flask.app import Microservice
+ms = Microservice(service="my-personal-microservice", path=__file__)
+```
+and a `config.yaml` file:
+
+```yaml
+my-personal-microservice:
+  DEBUG: true
+  TESTING: false
+```
+
+### Example 2
+```python
+from pyms.flask.app import Microservice
+ms = Microservice(service="ms1-api", path=__file__)
+```
+and a `config.yaml` file:
+
+```yaml
+ms1-api:
+  DEBUG: true
+  TESTING: false
+```

docs/examples.md

@@ -0,0 +1,40 @@
+# Examples
+
+```bash
+pip install py-ms
+```
+
+config.yml:
+
+```yaml
+my-minimal-microservice:
+  APP_NAME: "Python Microservice"
+```
+
+main.py
+
+```python
+from flask import jsonify
+
+from pyms.flask.app import Microservice
+
+ms = Microservice(service="my-minimal-microservice", path=__file__)
+app = ms.create_app()
+
+
+@app.route("/")
+def example():
+    return jsonify({"main": "hello world"})
+
+
+if __name__ == '__main__':
+    app.run()
+```
+
+```bash
+python main.py
+```
+
+Open in your browser http://localhost:5000/
+
+See [this Github page](https://github.com/python-microservices/pyms/tree/master/examples) to see a examples

docs/index.md

@@ -0,0 +1,15 @@
+# Welcome to PyMS
+
+PyMS, Python MicroService, is a collection of libraries, best practices and recommended ways to build 
+microservices with Python.
+
+## Index:
+* [PyMS structure](structure.md)
+* [Configuration](configuration.md)
+* [Services](services.md)
+* [Microservice class](ms_class.md)
+* [Quick start and examples](examples.md)
+* [Structure of a microservice project](structure_project.md)
+* Swagger and connexion
+* Tracing requests
+* [Services of PyMS](structure.md)

docs/ms_class.md

@@ -0,0 +1,95 @@
+# Microservices class
+
+The class Microservice is the core of all microservices built with PyMS. 
+
+
+You can create a simple microservice such as:
+
+```python
+from flask import jsonify
+
+from pyms.flask.app import Microservice
+
+ms = Microservice(service="my-minimal-microservice", path=__file__)
+app = ms.create_app()
+
+
+@app.route("/")
+def example():
+    return jsonify({"main": "hello world"})
+
+
+if __name__ == '__main__':
+    app.run()
+```
+
+And a config file like this config.yml
+
+```yaml
+my-minimal-microservice:
+  APP_NAME: "Python Microservice"
+```
+Check [Configuration](configuration.md) section to know how to create a configuration file.
+
+Each keyword in our configuration block, can be accessed in our Microservice object through the attribute `config`.
+
+```yaml
+# Config.yml
+example-config:
+  APP_NAME: "Python Microservice"
+  foo: "var"
+  multiplevars:
+    config1: "test1"
+    config2: "test2"
+  
+```
+```python
+#app.py
+from pyms.flask.app import Microservice
+
+ms = Microservice(service="example-config", path=__file__)
+print(ms.config.APP_NAME) 
+# >> "Python Microservice"
+print(ms.config.foo) 
+# >> "bar"
+print(ms.config.multiplevars.config1) 
+# >> "test1"
+print(ms.config.multiplevars.config2) 
+# >> "test2"
+```
+
+
+
+# Looking for Configuration file
+By default, Microservice class search a config.yml in the same path. You can set a different route or set a json file.
+To change this path, define a environment variable `CONFIGMAP_FILE`.
+
+This way of looking for the configuration is useful when you work with Docker and Kubernetes. For example, you can integrate
+a configmap of Kubernetes, with this microservice and a deployment with:
+
+```yaml
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: my-microservice
+spec:
+  replicas: 1
+  template:
+    spec:
+      containers:
+      - name: my-microservice
+        image: ...
+        env:
+          - name: CONFIGMAP_FILE
+            value: "/usr/share/microservice/config.yaml"
+
+        volumeMounts:
+          - mountPath: /usr/share/microservice
+            name: ms-config-volume
+      volumes:
+        - name: ms-config-volume
+          configMap:
+            name: my-microservice-configmap
+```
+
+Check more examples in [this Github page](https://github.com/python-microservices/pyms/tree/master/examples)

docs/services.md

@@ -0,0 +1,15 @@
+# Services
+
+Services are libraries, resources and extensions added to the Microservice in the configuration file.
+This services are created as an attribute of the [Microservice class](ms_class.md) to use in the code.
+
+To add a service check the [configuration section](configuration.md).
+
+Current services are:
+
+## Swagger / connexion
+Extends the Microservice with [Connexion](https://github.com/zalando/connexion)
+
+## Requests
+Extend the [requests library](http://docs.python-requests.org/en/master/) with trace headers and parsing JSON objects.
+Encapsulate common rest operations between business services propagating trace headers if set up.

docs/structure.md

@@ -0,0 +1,17 @@
+# Structure
+
+### pyms/config
+Module to read yaml or json configuration from a dictionary or a path.
+
+### pyms/flask/app
+With the function `create_app` initialize the Flask app, register [blueprints](http://flask.pocoo.org/docs/0.12/blueprints/)
+and initialize all libraries such as Swagger, database, trace system, custom logger format, etc.
+
+### pyms/flask/healthcheck
+This view is usually used by Kubernetes, Eureka and other systems to check if our application is running.
+
+### pyms/logger
+Print logger in JSON format to send to server like Elasticsearch. Inject span traces in logger.
+
+### pyms/tracer
+Create an injector `flask_opentracing.FlaskTracer` to use in our projects.

docs/structure_project.md

@@ -0,0 +1,3 @@
+#Project structure
+
+See [Microservice Scaffold](https://microservices-scaffold.readthedocs.io/en/latest/structure.html) for more info.

examples/mininum_microservice_docker/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.6.4-alpine3.7
+
+RUN apk add --update curl gcc g++ git libffi-dev openssl-dev python3-dev build-base linux-headers \
+    && rm -rf /var/cache/apk/*
+
+ENV PYTHONUNBUFFERED=1 APP_HOME=/microservice/
+ENV CONFIGMAP_FILE="$APP_HOME"config-docker.yml
+
+RUN mkdir $APP_HOME && adduser -S -D -H python
+RUN chown -R python $APP_HOME
+WORKDIR $APP_HOME
+
+ADD requirement*.txt $APP_HOME
+RUN pip install --upgrade pip
+RUN pip install -r requirements.txt
+
+ADD . $APP_HOME
+
+EXPOSE 5000
+USER python
+
+CMD ["gunicorn", "--worker-class", "gevent", "--workers", "8", "--log-level", "INFO", "--bind", "0.0.0.0:5000", "manage:app"]