Merge branch 'feature/update_docs' into develop

Author: avara1986

.travis.yml

@@ -3,16 +3,23 @@ sudo: false
 cache: false
 python:
     - '3.6'
+addons:
+  apt:
+    sources:
+      - deadsnakes
+    packages:
+    - python3.5
+    - python3.5-dev
 install:
-  - pip install -r requirements-tests.txt
+  - pip install -U tox coveralls
 
 script:
   - coverage erase
-  - coverage run -m  unittest
+  - tox
 after_success:
   - coverage combine
   - coveralls
 
 notifications:
   email:
-    - a.vara.1986@gmail.com
+    - a.vara.1986@gmail.com

app.py

@@ -0,0 +1,8 @@
+from flask import Flask
+
+app = Flask(__name__)
+
+
+@app.route('/')
+def pull_requests():
+    return 'Hello world'

docs/configuration.rst

@@ -1,5 +1,23 @@
 Configuration
 =============
 
+The project is configured in `project/config.py`. You must set the project name `APP_NAME` and the path prefix
+of the project `APPLICATION_ROOT`. This constants is defined in the class Config:
 
+.. code-block:: python
 
+    class Config:
+        DEBUG = False
+        TESTING = False
+        APP_NAME = "Template"
+        APPLICATION_ROOT = "/template"
+
+Documentation
+-------------
+The Microservice create a URL to inspect the Swagger documentation of the api in:
+
+.. code-block:: bash
+    localhost:5000/[APPLICATION_ROOT]/apidocs/
+
+Our API Rest work with `Flasgger <https://github.com/rochacbruno/flasgger>`_. You can see Flasgger docs or the official
+`Swagger documentation <https://swagger.io/specification/>`_ to add the syntax to your APIS and create your Swagger docs

docs/index.rst

@@ -24,3 +24,4 @@ Content
    structure
    configuration
    codeexample
+   project

docs/installation.rst

@@ -1,3 +1,74 @@
 Installation
 ============
 
+Clone the project
+
+.. code-block:: bash
+    git clone https://github.com/python-microservices/microservices-scaffold.git
+
+Configure your project and the path of your MS. See :doc:`configuration </configuration>` section.
+
+Configure your setup.py with your project information
+
+
+
+Use MS with Docker
+------------------
+`Install docker <https://docs.docker.com/install/>`_
+
+
+Use MS with Kubernetes localy
+-----------------------------
+Configure your service.yaml (TODO: create docs to configure kubernetes service.yaml)
+
+* Installing Kubernetes...
+
+.. code-block:: bash
+
+        curl -Lo kubectl https://storage.googleapis.com/kubernetes-release/release/v1.9.0/bin/linux/amd64/kubectl && chmod +x kubectl && sudo mv kubectl /usr/local/bin/
+
+* Installing Minikube...
+
+.. code-block:: bash
+
+        curl -Lo minikube https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 && chmod +x minikube && sudo mv minikube /usr/local/bin/
+
+
+Start minikube and set the environment of docker
+
+.. code-block:: bash
+
+    minikube start
+    eval $(minikube docker-env)
+    kubectl config use-context minikube
+
+If a shell isn't your friend. You could use kubernetes web panel to see your pods:
+
+.. code-block:: bash
+
+    minikube dashboard
+
+Create your image
+
+.. code-block:: bash
+
+    docker build -t your-app:v1 .
+
+Deploy your images localy:
+
+.. code-block:: bash
+
+    kubectl create -f service.yaml
+    minikube service your-app
+
+
+Clean your environment
+
+.. code-block:: bash
+
+    kubectl delete service your-app
+    kubectl delete deployment your-app
+    docker rmi your-app:v1 -f
+    minikube stop
+    eval $(minikube docker-env -u)
+    minikube delete

docs/project.rst

@@ -0,0 +1,8 @@
+Project
+=======
+
+.. automodule:: project
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

docs/quickstart.rst

@@ -1,4 +1,7 @@
 Quickstart
 ==========
 
-
+.. code-block:: bash
+    git clone https://github.com/python-microservices/microservices-scaffold.git
+    cd microservices-scaffold
+    python manage.py runserver

docs/structure.rst

@@ -11,9 +11,40 @@ You have a project with this structure:
    ├ config.py
    ├ views
    │ ├ __init__.py
-   │ └ views.py
+   │ ├ views.py
+   │ └ healthcheck.py
    ├ models
    │ ├ __init__.py
    │ └ models.py
-   └ models
-     └ test_views.py
+   └ tests
+     └ test_views.py
+
+manager.py
+----------
+
+A Django style command line. Use this to start the application like:
+
+.. code-block:: bash
+    python manage.py runserver
+
+You can set the host and the port with:
+
+.. code-block:: bash
+    python manage.py runserver -h 0.0.0.0 -p 8080
+
+project/__init__.py
+-------------------
+This file init the project with the funcion `create_app`. Initialize the Flask app, register `blueprints <http://flask.pocoo.org/docs/0.12/blueprints/>`_
+and intialize all libraries like Swagger, database, the trace system...
+
+project/config.py
+-----------------
+See :doc:`configuration </configuration>` section
+
+project/views
+-------------
+use views.py or create your file. You must add after register the view blueprint in `project/views/__init__.py`.
+
+project/views/healthcheck.py
+----------------------------
+This views is usually used by Kubernetes, Eureka and other systems to check if our application is up and running

project/__init__.py

@@ -4,6 +4,8 @@
 
 from flasgger import Swagger
 from flask import Flask
+from flask_opentracing import FlaskTracer
+from jaeger_client import Config
 
 from project.config import CONFIG
 
@@ -45,34 +47,62 @@
 }
 
 
-class PrefixMiddleware(object):
+def init_jaeger_tracer(service_name='your-app-name'):
+    """This scaffold is configured whith `Jeager <https://github.com/jaegertracing/jaeger>`_ but you can use
+    one of the `opentracing tracers <http://opentracing.io/documentation/pages/supported-tracers.html>`_
+    :param service_name: the name of your application to register in the tracer
+    :return: opentracing.Tracer
+    """
+    config = Config(config={
+        'sampler': {'type': 'const', 'param': 1}
+    }, service_name=service_name)
+    return config.initialize_tracer()
+
 
+class PrefixMiddleware(object):
+    """Set a prefix path to all routes. This action is needed if you have a stack of microservices and each of them
+    exist in the same domain but different path. Por example:
+    * mydomain.com/ms1/
+    * mydomain.com/ms2/
+    """
     def __init__(self, app, prefix=''):
         self.app = app
         self.prefix = prefix
 
     def __call__(self, environ, start_response):
-
         if environ['PATH_INFO'].startswith(self.prefix):
             environ['PATH_INFO'] = environ['PATH_INFO'][len(self.prefix):]
             environ['SCRIPT_NAME'] = self.prefix
             return self.app(environ, start_response)
+        elif environ['PATH_INFO'].startswith("/healthcheck"):
+            return self.app(environ, start_response)
         else:
             start_response('404', [('Content-Type', 'text/plain')])
             return ["This url does not belong to the app.".encode()]
 
 
 def create_app():
+    """Initialize the Flask app, register blueprints and intialize all libraries like Swagger, database, the trace system...
+    return the app and the database objects.
+    :return:
+    """
     from project.models import db
     from project.views import views_bp as views_blueprint
+    from project.views import views_hc as views_hc_blueprint
     environment = os.environ.get("ENVIRONMENT", "default")
 
     app = Flask(__name__)
     app.config.from_object(CONFIG[environment])
     app.wsgi_app = PrefixMiddleware(app.wsgi_app, prefix=app.config["APPLICATION_ROOT"])
 
+
+    if not app.config["TESTING"] and not app.config["DEBUG"]:
+        j_tracer = init_jaeger_tracer(app.config["APP_NAME"])
+        FlaskTracer(j_tracer, True, app)
+
     db.init_app(app)
 
+    # Initialize Swagger
     SWAGGER_CONFIG["specs"][0]["route"] = SWAGGER_CONFIG["specs"][0]["route"].format(
         application_root=app.config["APPLICATION_ROOT"]
     )
@@ -87,7 +117,9 @@ def create_app():
     )
     Swagger(app, config=SWAGGER_CONFIG)
 
+    # Initialize Blueprints
     app.register_blueprint(views_blueprint)
+    app.register_blueprint(views_hc_blueprint)
     with app.test_request_context():
         db.create_all()
     return app, db

project/views/__init__.py

@@ -4,5 +4,6 @@
 from flask import Blueprint
 
 views_bp = Blueprint('views', __name__, static_url_path='/static')
+views_hc = Blueprint('healthcheck', __name__, static_url_path='/static')
 
-from project.views import views
+from project.views import views, healthcheck