A python microservice framework


Get started
Write an API specification
Implement your API
Docker packaging
Deploy to AWS Beanstalk
JWT authentication
Error handling
Asynchronous execution
Database serialisation

Packaging with Docker

PyMacaron microservices are designed to be packaged as Docker images. pymacaron-docker contains the tools required to build a Docker image containing and starting your microservice.


You need to be able to run a docker container locally on your development host, as part of the deployment pipeline for PyMacaron microservices. Simply install docker engine as follows:

apt-get install docker docker-engine

And install pymacaron-docker:

pip install pymacaron-docker


Make sure that the following key pairs are set in your project’s ‘pym-config.yaml’:

docker_repo: <MYREPO>

Your microservice’s Docker image will be named ‘-' where '' is a unique number generated based on the date and the git revision number of your project.

Login to your docker repository

Using the same unix user with which you will later run the deployment pipeline, login to the Docker repository to which your microservice’s image will be uploaded (‘docker_repo’ in ‘pym-config.yaml’):

docker login

This creates the file ‘~/.docker/config.json file’ containing your docker auth token.


PyMacaron microservices are designed to support multiple deployment targets. For the moment however, only AWS Beanstalk is supported.

Deployment pipeline with pymdeploy

bin/pymdeploy implements the deployment pipeline of PyMacaron microservices, which consists of the following steps:

  1. Execute unittests under ‘test/’ with nosetests. Stop if tests fail.

  2. Generate a docker image in which the app starts inside gunicorn.

  3. Start this image in a local docker instance and run acceptance tests from the ‘testaccept/’ directory against it. Stop if tests fail.

  4. Push that image to

  5. Deploy the image to a live environment, AWS Beanstalk or other, as specified in pym-config.yaml.

  6. Run acceptance tests again, this time against the live environment, as a final validation.


To execute the full deployment pipeline, do:

cd your-project-root

For more usage examples, see ‘pymdeploy –help’.