Skip to content

Commit

Permalink
📝 Update links and format
Browse files Browse the repository at this point in the history
  • Loading branch information
tiangolo committed May 15, 2019
1 parent 86fdb60 commit a93c9d8
Showing 1 changed file with 4 additions and 27 deletions.
31 changes: 4 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
[![Build Status](https://travis-ci.org/tiangolo/meinheld-gunicorn-flask-docker.svg?branch=master)](https://travis-ci.org/tiangolo/meinheld-gunicorn-flask-docker)


## Supported tags and respective `Dockerfile` links

* [`python3.7`, `latest` _(Dockerfile)_](https://github.com/tiangolo/meinheld-gunicorn-flask-docker/blob/master/python3.7/Dockerfile)
Expand All @@ -9,15 +8,13 @@
* [`python3.6-alpine3.8` _(Dockerfile)_](https://github.com/tiangolo/meinheld-gunicorn-flask-docker/blob/master/python3.6-alpine3.8/Dockerfile)
* [`python3.7-alpine3.8` _(Dockerfile)_](https://github.com/tiangolo/meinheld-gunicorn-flask-docker/blob/master/python3.7-alpine3.8/Dockerfile)


# meinheld-gunicorn-flask

[**Docker**](https://www.docker.com/) image with [**Meinheld**](http://meinheld.org/) managed by [**Gunicorn**](https://gunicorn.org/) for high-performance web applications in [**Flask**](http://flask.pocoo.org/) using **[Python](https://www.python.org/) 3.7** and **3.6** with performance auto-tuning. Optionally with Alpine Linux.

**GitHub repo**: <https://github.com/tiangolo/meinheld-gunicorn-flask-docker>

**Docker Hub image**: <https://hub.docker.com/r/tiangolo/meinheld-gunicorn-flask/>
**GitHub repo**: [https://github.com/tiangolo/meinheld-gunicorn-flask-docker](https://github.com/tiangolo/meinheld-gunicorn-flask-docker)

**Docker Hub image**: [https://hub.docker.com/r/tiangolo/meinheld-gunicorn-flask/](https://hub.docker.com/r/tiangolo/meinheld-gunicorn-flask/)

## Description

Expand All @@ -27,7 +24,6 @@ If you have an already existing application in Flask or are building a new one,

This image has an "auto-tuning" mechanism included, so that you can just add your code and get **good performance** automatically. And without making sacrifices (like logging).


### * Note on performance and features

If you are starting a new project, you might benefit from a newer and faster framework like [**FastAPI**](https://github.com/tiangolo/fastapi) (based on ASGI instead of WSGI like Flask and Django), and a Docker image like [**tiangolo/uvicorn-gunicorn-fastapi**](https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker).
Expand All @@ -36,7 +32,6 @@ It would give you about 200% the performance achievable with Flask, even when us

Also, if you want to use new technologies like WebSockets it would be easier with a newer framework based on ASGI, like **FastAPI**. As the standard ASGI was designed to be able to handle asynchronous code like the one needed for WebSockets.


## Python 2.7

Do you need support for Python 2.7?
Expand All @@ -47,29 +42,24 @@ But only after knowing that someone actually needs it.

## Technical Details


### Meinheld

**Meinheld** is a high-performance WSGI-compliant web server.


### Gunicorn

You can use **Gunicorn** to manage Meinheld and run multiple processes of it.


### Flask

Flask is a microframework for Python based on Werkzeug, Jinja 2 and good intentions.


## Alternatives

This image was created to be an alternative to [**tiangolo/uwsgi-nginx-flask**](https://github.com/tiangolo/uwsgi-nginx-flask-docker), providing about 400% the performance of that image.

It is based on the more generic image [**tiangolo/meinheld-guinicorn**](https://github.com/tiangolo/meinheld-guinicorn-docker). That's the one you would use for other WSGI frameworks, like Django.


## How to use

* You don't need to clone the GitHub repo. You can use this image as a base image for other images, using this in your `Dockerfile`:
Expand Down Expand Up @@ -98,7 +88,6 @@ docker build -t myimage ./

These are the environment variables that you can set in the container to configure it and their default values:


#### `MODULE_NAME`

The Python "module" (file) to be imported by Gunicorn, this module would contain the actual Flask application in a variable.
Expand All @@ -114,7 +103,6 @@ For example, if your main file was at `/app/custom_app/custom_main.py`, you coul
docker run -d -p 80:80 -e MODULE_NAME="custom_app.custom_main" myimage
```


#### `VARIABLE_NAME`

The variable inside of the Python module that contains the Flask application.
Expand All @@ -140,7 +128,6 @@ In this case `api` would be the variable with the "Flask application". You could
docker run -d -p 80:80 -e VARIABLE_NAME="api" myimage
```


#### `APP_MODULE`

The string with the Python module and the variable name passed to Gunicorn.
Expand All @@ -156,7 +143,6 @@ You can set it like:
docker run -d -p 80:80 -e APP_MODULE="custom_app.custom_main:api" myimage
```


#### `GUNICORN_CONF`

The path to a Gunicorn Python configuration file.
Expand All @@ -173,7 +159,6 @@ You can set it like:
docker run -d -p 80:80 -e GUNICORN_CONF="/app/custom_gunicorn_conf.py" myimage
```


#### `WORKERS_PER_CORE`

This image will check how many CPU cores are available in the current server running your container.
Expand Down Expand Up @@ -202,7 +187,6 @@ docker run -d -p 80:80 -e WORKERS_PER_CORE="0.5" myimage

In a server with 8 CPU cores, this would make it start only 4 worker processes.


#### `WEB_CONCURRENCY`

Override the automatic definition of number of workers.
Expand All @@ -219,7 +203,6 @@ docker run -d -p 80:80 -e WEB_CONCURRENCY="2" myimage

This would make the image start 2 worker processes, independent of how many CPU cores are available in the server.


#### `HOST`

The "host" used by Gunicorn, the IP where Gunicorn will listen for requests.
Expand Down Expand Up @@ -250,15 +233,14 @@ You can set it like:
docker run -d -p 80:8080 -e PORT="8080" myimage
```


#### `BIND`

The actual host and port passed to Gunicorn.

By default, set based on the variables `HOST` and `PORT`.

So, if you didn't change anything, it will be set by default to:

* `0.0.0.0:80`

You can set it like:
Expand All @@ -267,7 +249,6 @@ You can set it like:
docker run -d -p 80:8080 -e BIND="0.0.0.0:8080" myimage
```


#### `LOG_LEVEL`

The log level for Gunicorn.
Expand Down Expand Up @@ -302,10 +283,9 @@ You can override it by including a file in:
* `/app/app/gunicorn_conf.py`
* `/gunicorn_conf.py`


### Custom `/app/prestart.sh`

If you need to run anything before starting the app, you can add a file `prestart.sh` to the directory `/app`. The image will automatically detect and run it before starting everything.
If you need to run anything before starting the app, you can add a file `prestart.sh` to the directory `/app`. The image will automatically detect and run it before starting everything.

For example, if you want to add Alembic SQL migrations (with SQLALchemy), you could create a `./app/prestart.sh` file in your code directory (that will be copied by your `Dockerfile`) with:

Expand All @@ -329,12 +309,10 @@ If you need to run a Python script before starting the app, you could make the `
python /app/my_custom_prestart_script.py
```


## Tests

All the image tags, configurations, environment variables and application options are tested.


## Release Notes

### Next Release
Expand All @@ -347,7 +325,6 @@ All the image tags, configurations, environment variables and application option

* Add support for `/app/prestart.sh`.


## License

This project is licensed under the terms of the MIT license.

0 comments on commit a93c9d8

Please sign in to comment.