Package: agaveflask
# agaveflask ### Overview ##A common set of Python modules for writing flask services for the Agave Platform. The package officially requires Python3.4+, though some functionality may work with Python 2.## Installation ##pip install agaveflaskRequires Python header files and a C++ compiler on top of gcc. On Debian/Ubuntu systems:apt-get install python3-dev g++## Usage ##agaveflask provides the following modules:* auth.py - configurable authentication/authorization routines.* config.py - config parsing.* errors.py - exception classes raised by agaveflask.* store.py - python bindings for persistence.* utils.py - general request/response utilities.It relies on a configuration file for the service. Create a file called service.conf in one of `/`, `/etc`, or `$pwd`.See service.conf.ex in this repository for settings used by this library.## Using Docker ##### Packaging ###If you are packaging your flask service with Docker, agaveflask provides a base image, agaveapi/flask_api, thatsimplifies your Dockerfile and provides a configurable entrypoint for both development and production deployments. Inmost cases, all you need to do is add your service code and your requirements.txt file. For example, if you have aflask service with a requirements.txt file and code that resides in a directory called "service", the Dockerfile canbe as simple as:```from agaveapi/flask_apiADD requirements.txt /requirements.txtRUN pip install -r /requirements.txtADD service /service```### Suggested Package Layout ###For simple microservices, we make the following recommendations for minimal configuration at deployment time.* Place the service code in a Python package called `service` that resides at the root of the Docker image (i.e. `/service`).* Within `/service`, have a python module called `api.py` where the wsgi application is instantiated.* Call the actual wsgi application object `app`.Beyond standard flask operations, additional suggestions for the `api.py` module include:* Add cors support.* Set up authentication and authorization for your API using the agaveflask authn_and_authz() method.* Start a development server within `__main__`.Here is a typical example:```from flask import Flaskfrom flask_cors import CORSfrom agaveflask.utils import AgaveApi, handle_errorfrom agaveflask.auth import authn_and_authzfrom resources import JwtResource# create the wsgi application objectapp = Flask(__name__)# add CORS supportCORS(app)# create an AgaveApi object so that convenience utilities are available:api = AgaveApi(app)# Set up Authn/z for the API@app.before_requestdef auth():authn_and_authz()# Set up error handling@app.errorhandler(Exception)def handle_all_errors(e):return handle_error(e)# Add the resourcesapi.add_resource(JwtResource, '/admin/jwt')# start a development serverif __name__ == '__main__':app.run(host='0.0.0.0', debug=True)```### Deployment Configuration ###The entry point is configured through environmental variables. Using the `server` variable toggles between adevelopment server you have created in your api module and gunicorn, meant for production.All other settings are used to help the entrypoint findyour wsgi application. If you are able to use the recommended file system structure and layout, you may be able torely exclusively on the image defaults.Here is a complete list of config variables, their usage, and their default values:* server: Value 'dev' attempts to starts up a development server by executing your module's `__main__` method. Anyother value starts up gunicorn. Default is 'dev'.* package: path to package containing service code (no trailing slash). Default is '/service'.* module: name of python module (not including '.py') containing the wsgi application object. Default is 'api'.* app: name of the wsgi application object. Default is 'app'.* port: port to start the server on when running with gunicorn. Default is 5000.### Docker compose Example ###The following snippet from a hypothetical docker-compose.yml file illustrates typical usage. In this example we have afolder, `services`, containing two services like so:* `/services/serviceA/api.py`* `/services/serviceB/api.py`We are bundling into the same docker image (`jdoe/my_services`). Because of this we need to set the indvidual packages for each using environmental variables. We also set the servervariable so that we use gunicorn.```.  .  .serviceA:image: jdoe/my_servicesports:- "5000:5000"volumes:- ./local-dev.conf:/etc/service.confenvironment:package: /services/serviceAserver: gunicornserviceB:image: jdoe/my_servicesports:- "5001:5000"volumes:- ./local-dev.conf:/etc/service.confenvironment:package: /services/serviceAserver: gunicorn.  .  .```