Package: ep
[![Build Status](https://travis-ci.org/txels/ep.svg)](https://travis-ci.org/txels/ep)[![Code Health](https://landscape.io/github/txels/ep/master/landscape.svg)](https://landscape.io/github/txels/ep/master)[![Can I Use Python 3?](https://caniusepython3.com/check/00276696-d27c-46f0-b10e-0c7bd684f786.svg)](https://caniusepython3.com/check/00276696-d27c-46f0-b10e-0c7bd684f786)# epA tool to support an explicit contract between application and plaftorm.Inspired by Heroku's post about [an explicit contract between application andplatform](https://blog.heroku.com/archives/2011/6/28/the_new_heroku_4_erosion_resistance_explicit_contracts),`ep` aims to provide a reusable mechanism to cover that contract.As a summary, Heroku's contract is based on:- Dependency management: declared as part of the codebase- Procfile: as a mechanism to specify what should be run- Web process binds to $PORT (an externally provided environment variable- stdout for logs- Resource handles in the environment: environment variables for configuration,in particular for connecting to external resources## What defines a contract in `ep`An `ep`-based contract tries to cover these areas:- A defined way to specify your dependencies- A defined way to run your project- Configured purely via environment variablesThe particulars of the contract are specified via a configuration file thatlives on the root of your application's repository. This configuration fileis in YAML format and is called `ep.yml` by default.### A defined way to specify dependenciesDependencies can be of various types. `ep` aims to cover at least thefollowing:- `python`: via pip install of a requirements file. Defaults to`requirements.txt` at the root folder- `node`: via npm install of a package file. Defaults to `package.json` atthe root> The root here refers to the directory where `ep.yml` lives.> Future extensions may cover ruby gems, bower packages, and even os-level> packages on some OSesThere are two types of dependencies from the PoV of `ep`:- Those that the tool will be able to install- Those that it will only verify, but not attempt to install. These includee.g. the version of Python in your systemSome of these dependencies will have their defaults.This could be a partial example of a `ep.yml`.```yamlep: 1.0.0dependencies:- pythonversion: 2.7file: requirements/runtime.txt- npm```The command to install dependencies via ep is:ep setup`ep` will always install dependencies in an isolated environment. This meanse.g. a virtual environment in Python, local npm install etc. `ep` will managethe creation of this isolated environment for you.You can always delete installed dependencies for a fresh initial state:ep clear### A defined way to run your project`ep` doesn't force you to use `Procfile`, but lets you define your runcommand:```yamlrun: gunicorn myapp.wsgi```Defaults to running a `Procfile` in your root.Run your project using:ep runYou can also run multiple commands:```yamlrun:- echo "Starting ..."- gunicorn myapp.wsgi```### Configuration via environment variablesYour app should be configurable via environment variables. Your `ep.yml` fileprovides an explicit definition of what those variables are, and optionaldefault values and help.You should include in an `env` section the environment variables your systemrelies on for running, add help text for them, and when applicable definesome defaults:```yamlenv:PORT:help: "The port the web application will run on"SOME_EXTERNAL_SERVICE_URL:help: "URL to your external service blah."default: "http://localhost:9000"````ep run` will complain if variables that do not have a default value are notprovided, and refuse to run.### Performing additional checksBesides default checks for dependency management and environment variables,you can add custom check steps. As for `run`, these can be a single stringor a list:```yamlcheck:- python -m unittest discover- flake8 ep```## Additional featuresBesides the basic explicit contract defined above, `ep` helps you with extrathings.### Some commands`ep shell` runs commands within ep's isolated environment. E.g.:ep shell "pip list"### Extra setup stepsTODO: define a mechanism to have additional setup steps such as runningmigrations on a django project, etc...