{"id":21027288,"url":"https://github.com/bynect/hypercorn-fastapi-docker","last_synced_at":"2025-07-13T01:04:17.796Z","repository":{"id":47258084,"uuid":"300272199","full_name":"bynect/hypercorn-fastapi-docker","owner":"bynect","description":"Docker image with Hypercorn for FastAPI apps in Python 3.7, 3.8, 3.9. Ready for HTTP2 and HTTPS","archived":false,"fork":false,"pushed_at":"2021-09-06T11:36:35.000Z","size":98,"stargazers_count":26,"open_issues_count":0,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-03T07:51:15.687Z","etag":null,"topics":["alpine","asgi","asyncio","docker","docker-image","docker-images","dockerfile","fastapi","fastapi-docker","http2","https","hypercorn","python","python3","python37","python38","python39","trio","web","wsgi"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bynect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-01T12:31:26.000Z","updated_at":"2024-11-16T20:20:51.000Z","dependencies_parsed_at":"2022-09-01T11:50:27.845Z","dependency_job_id":null,"html_url":"https://github.com/bynect/hypercorn-fastapi-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bynect%2Fhypercorn-fastapi-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bynect%2Fhypercorn-fastapi-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bynect%2Fhypercorn-fastapi-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bynect%2Fhypercorn-fastapi-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bynect","download_url":"https://codeload.github.com/bynect/hypercorn-fastapi-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254323071,"owners_count":22051708,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine","asgi","asyncio","docker","docker-image","docker-images","dockerfile","fastapi","fastapi-docker","http2","https","hypercorn","python","python3","python37","python38","python39","trio","web","wsgi"],"created_at":"2024-11-19T11:49:22.070Z","updated_at":"2025-05-15T10:32:24.898Z","avatar_url":"https://github.com/bynect.png","language":"Dockerfile","readme":"\n[![Deploy](https://github.com/bynect/hypercorn-fastapi/workflows/Deploy/badge.svg?branch=main)](https://github.com/bynect/hypercorn-fastapi-docker/actions?query=workflow%3ADeploy)\n\n## Image tags and Dockerfiles\n\n* [`python3.9`, `latest`](images/python3.9.dockerfile) (**[*](#python-39-support)**)\n* [`python3.9-slim`](images/python3.9-slim.dockerfile) (**[*](#python-39-support)**)\n* [`python3.9-alpine`](images/python3.9-alpine.dockerfile) (**[*](#python-39-support)**)\n* [`python3.8`](images/python3.8.dockerfile)\n* [`python3.8-slim`](images/python3.8-slim.dockerfile)\n* [`python3.8-alpine`](images/python3.8-alpine.dockerfile)\n* [`python3.7`](images/python3.7.dockerfile)\n* [`python3.7-slim`](images/python3.7-slim.dockerfile)\n* [`python3.7-alpine`](images/python3.7-alpine.dockerfile)\n\n# **hypercorn-fastapi-docker**\n\nDocker image with [Hypercorn][hypercorn site] for [FastAPI][fastapi site] application in Python 3.7+. With slim and alpine options.\n\n* **[Github repo][github repo]**\n* **[Docker hub][docker repo]**\n\n## Hypercorn\n**[Hypercorn][hypercorn site]** is an HTTP2 ready ASGI web server based on the sans-io hyper, h11, h2, and wsproto libraries and inspired by Gunicorn.\n\nHypercorn supports HTTP/1, HTTP/2, WebSockets (over HTTP/1 and HTTP/2), ASGI/2, and ASGI/3 specifications. Hypercorn can utilise asyncio, uvloop, or trio worker types.\n\n## FastAPI\n**[FastAPI][fastapi site]** is a modern, fast (high-performance), web framework for building APIs with Python 3.6+.\n\nThe key features are:\n\n* Fast: Very high performance, on par with NodeJS and Go (thanks to Starlette and Pydantic).\n* Fast to code: Increase the speed to develop features by about 300% to 500% *.\n* Less bugs: Reduce about 40% of human (developer) induced errors. *\n* Intuitive: Great editor support. Completion everywhere. Less time debugging.\n* Easy: Designed to be easy to use and learn. Less time reading docs.\n* Short: Minimize code duplication. Multiple features from each parameter declaration. Less bugs.\n* Robust: Get production-ready code. With automatic interactive documentation.\n* Standards-based: Based on (and fully compatible with) the open standards for APIs: OpenAPI (previously known as Swagger) and JSON Schema.\n\n\u003csmall\u003e* estimation based on tests on an internal development team, building production applications.\u003c/small\u003e\n\n## How to start\n* You can use this image as a base image for other images, using this in your Dockerfile:\n\n```dockerfile\nFROM bynect/hypercorn-fastapi:python3.8-slim\n\nCOPY ./app /app\n```\nIt will expect a file either at `/app/app/main.py` and `/app/main` containing the variable `app` containing your FastAPI application.\n\nThen you can build you Dockerfile, e.g:\n```sh\n$ docker build -t myimage ./\n```\n\n# Usage\n## Environment variables\nThese are the environment variables that you can set in the container to configure it and their default values.\nYou can set alternative values for them either from shell or from Dockerfile, e.g:\n```sh\n#from shell\n$ docker run -d -p 80:80 -e MODULE_NAME=\"custom_app.custom_main\" myimage\n```\n```dockerfile\n#from Dockerile\nFROM bynect/hypercorn-fastapi:python3.8-slim\n\nENV MODULE_NAME=\"custom_app.custom_main\"\n\nCOPY ./app /app\n```\n\n\n#### `MODULE_NAME`\n\nThe Python \"module\" (file) to be imported by Hypercorn, this module would contain the actual application in a variable.\n\nBy default:\n\n* `app.main` if there's a file `/app/app/main.py` or\n* `main` if there's a file `/app/main.py`\n\nFor example, if your main file was at `/app/custom_app/custom_main.py`, you could set it like:\n\n```sh\n$ docker run -d -p 80:80 -e MODULE_NAME=\"custom_app.custom_main\" myimage\n```\n\n\n#### `VARIABLE_NAME`\n\nThe variable inside of the Python module that contains the FastAPI application.\n\nBy default:\n\n* `app`\n\nFor example, if your main Python file has something like:\n\n```python\nfrom fastapi import FastAPI\n\napi = FastAPI()\n\n\n@api.get(\"/\")\ndef read_root():\n    return {\"Hello\": \"World\"}\n```\n\nIn this case `api` would be the variable with the FastAPI application. You could set it like:\n\n```sh\n$ docker run -d -p 80:80 -e VARIABLE_NAME=\"api\" myimage\n```\n\n\n#### `APP_MODULE`\n\nThe string with the Python module and the variable name passed to Hypercorn.\n\nBy default, set based on the variables `MODULE_NAME` and `VARIABLE_NAME`:\n\n* `app.main:app` or\n* `main:app`\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:80 -e APP_MODULE=\"custom_app.custom_main:api\" myimage\n```\n\n\n#### `HYPERCORN_CONF`\n\nThe path to a Hypercorn Python configuration file.\n\nBy default:\n\n* `/app/app/hypercorn_conf.py` if file exists\n* `/app/hypercorn_conf.py` if file exists\n* `/hypercorn_conf.py` included file\n\n\u003csmall\u003e* ordered by priority.\u003c/small\u003e\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:80 -e GUNICORN_CONF=\"/app/custom_gunicorn_conf.py\" myimage\n```\n\n**Note**: that `HYPERCORN_CONF` needs the prefix `file:` for Python file, `python:` for Python module and no prefix for TOML file.\n\n\n#### `WORKERS_PER_CORE`\n\nThis image will check how many CPU cores are available in the current server running your container.\n\nIt will set the number of workers to the number of CPU cores multiplied by this value.\n\nBy default:\n\n* `1`\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:80 -e WORKERS_PER_CORE=\"3\" myimage\n```\n\nIf you used the value `3` in a server with 2 CPU cores, it would run 6 worker processes.\n\nYou can use floating point values too.\n\nSo, for example, if you have a big server (let's say, with 8 CPU cores) running several applications, and you have a FastAPI application that you know won't need high performance. And you don't want to waste server resources. You could make it use `0.5` workers per CPU core. For example:\n\n```sh\n$ docker run -d -p 80:80 -e WORKERS_PER_CORE=\"0.5\" myimage\n```\n\nIn a server with 8 CPU cores, this would make it start only 4 worker processes.\n\n\n#### `MAX_WORKERS`\n\nSet the maximum number of workers to use.\n\nYou can use it to let the image compute the number of workers automatically but making sure it's limited to a maximum.\n\nThis can be useful, for example, if each worker uses a database connection and your database has a maximum limit of open connections.\n\nBy default it's not set, meaning that it's unlimited.\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:80 -e MAX_WORKERS=\"24\" myimage\n```\n\nThis would make the image start at most 24 workers, independent of how many CPU cores are available in the server.\n\n\n#### `WEB_CONCURRENCY`\n\nOverride the automatic definition of number of workers.\n\nBy default:\n\n* Set to the number of CPU cores in the current server multiplied by the environment variable `WORKERS_PER_CORE`. So, in a server with 2 cores, by default it will be set to `2`.\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:80 -e WEB_CONCURRENCY=\"2\" myimage\n```\n\nThis would make the image start 2 worker processes, independent of how many CPU cores are available in the server.\n\n\n#### `HOST`\n\nThe \"host\" used by Hypercorn, the IP where Hypercorn will listen for requests.\n\nIt is the host inside of the container.\n\nSo, for example, if you set this variable to `127.0.0.1`, it will only be available inside the container, not in the host running it.\n\nIt's is provided for completeness, but you probably shouldn't change it.\n\nBy default:\n\n* `0.0.0.0`\n\n\n#### `TCP_PORT`\n\nThe tcp port the container should listen on when `USE_TCP` is set to true.\n\nIf you are running your container in a restrictive environment that forces you to use some specific port (like `8080`) you can set it with this variable.\n\nBy default:\n\n* `80`\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e TCP_PORT=\"8080\" myimage\n```\n\n\n#### `USE_SSL`\n\nIf Hypercorn will use ssl-related options. When false ssl-related options are not used.\n\nBy default is set to:\n* `false`\n\n\u003eDepends on `CA_CERTS` - `CERTFILE` - `KEYFILE`\n\u003eAt least one of `USE_SSL` and `USE_TCP` **MUST** be set to true.\n\n\n#### `USE_TCP`\n\nIf Hypercorn will use tcp-related options. When false tcp-related options are not used.\n\nBy default is set to:\n* `true`\n\n\u003eAt least one of `USE_SSL` and `USE_TCP` **MUST** be set to true.\n\n\n#### `SSL_PORT`\n\nThe ssl port the container should listen on when `USE_SSL` is set to true.\n\nIf you are running your container in a restrictive environment that forces you to use some specific port (like `8000`) you can set it with this variable.\n\nBy default:\n\n* `443`\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 443:8000 -e SSL_PORT=\"8000\" myimage\n```\n\u003eDepens on `USE_SSL`\n\n\n#### `BIND`\n\nThe actual host and port passed to Hypercorn.\n\nIf `USE_SSL` is set to true the default value will be based on `HOST` and `SSL_PORT`.\nSo, if you didn't change anything, it will be set by default to:\n\n* `0.0.0.0:443`\n\nOtherwise, if `USE_SSL` is not set to true, the value will be based on `HOST` and `TCP_PORT`.\nSo, if you didn't change anything, it will be set by default to:\n\n* `0.0.0.0:80`\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e BIND=\"0.0.0.0:8080\" myimage\n```\n\n\n#### `INSECURE_BIND`\n\nThe host and port passed to Hypercorn as fallback in HTTPS connections.\n\nIf `USE_SSL` and `USE_TCP` are both true the default value is based on the variables `HOST` and `TCP_PORT`.\n\nSo, if you didn't change anything, it will be set by default to:\n\n* `0.0.0.0:80`\n\nOtherwise, if `USE_SSL` is not set to true or `USE_TCP` is set to false, the value will be set to `None`.\n\nYou can manually set only when the aforementioned conditions are true.\n\u003eDepens on `USE_SSL` and `USE_TCP`\n\n#### `QUIC_BIND`\n\nQuic bind to be used instead of bind. By default it's not set.\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e QUIC_BIND=\"0.0.0.0:8080\" myimage\n```\n\n\n#### `LOG_LEVEL`\n\nThe log level for Hypercorn.\n\nOne of:\n\n* `debug`\n* `info`\n* `warning`\n* `error`\n* `critical`\n\nBy default, set to `info`.\n\nIf you need to squeeze more performance sacrificing logging, set it to `warning`, for example:\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e LOG_LEVEL=\"warning\" myimage\n```\n\n#### `WORKER_CLASS`\n\nThe worker class to be used by Hypercorn.\n\nBy default, set to `asyncio`.\n\nThe three avaible values are:\n* `asyncio`\n* `uvloop`\n* `trio`\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e WORKER_CLASS=\"uvloop\" myimage\n```\n\n\n#### `CA_CERTS`\n\nPath to CA certificate file. By default it's not set.\n\n\u003eDepends on `USE_SSL`\n\n\n#### `CERTFILE`\n\nPath to CA certificate file. By default it's not set.\n\n\u003eDepends on `USE_SSL`\n\n\n#### `KEYFILE`\n\nPath to CA certificate file. By default it's not set.\n\n\u003eDepends on `USE_SSL`\n\n\n#### `CIPHERS`\n\nCiphers used by ssl connection. By default:\n* `\"ECDHE+AESGCM\"`\n\n\u003eDepends on `USE_SSL`\n\n\n#### `KEEP_ALIVE`\n\nThe number of seconds to wait for requests on a Keep-Alive connection.\n\nBy default, set to `5`.\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e KEEP_ALIVE=\"20\" myimage\n```\n\n\n#### `GRACEFUL_TIMEOUT`\n\nTimeout for graceful workers restart.\n\nBy default, set to `120`.\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e GRACEFUL_TIMEOUT=\"20\" myimage\n```\n\n\n#### `ACCESS_LOG`\n\nThe access log file to write to.\n\nBy default `\"-\"`, which means stdout (print in the Docker logs).\n\nIf you want to disable `ACCESS_LOG`, set it to an empty value.\n\nFor example, you could disable it with:\n\n```sh\n$ docker run -d -p 80:8080 -e ACCESS_LOG= myimage\n```\n\n\n#### `ERROR_LOG`\n\nThe error log file to write to.\n\nBy default `\"-\"`, which means stderr (print in the Docker logs).\n\nIf you want to disable `ERROR_LOG`, set it to an empty value.\n\nFor example, you could disable it with:\n\n```sh\n$ docker run -d -p 80:8080 -e ERROR_LOG= myimage\n```\n\n\n#### `BACKLOG`\n\nThe maximum number of pending connections. By default set to `100`.\n\n\n#### `PRE_START_PATH`\n\nThe path where to find the pre-start script.\n\nBy default, set to `/app/prestart.sh`.\n\nYou can set it like:\n\n```sh\n$ docker run -d -p 80:8080 -e PRE_START_PATH=\"/custom/script.sh\" myimage\n```\n\n\n## Prestart script\nIf you need to run anything before starting the app, you can add a file prestart.sh to the directory `/app`.\nThe image will automatically detect and run it before starting everything.\nIf you need to run a Python script before starting the app, you could make the /app/prestart.sh file run your Python script, with something like:\n\n```sh\n#! /usr/bin/env bash\n\n# Run custom Python script before starting\npython /app/my_custom_prestart_script.py\n```\nYou can customize the location of the prestart script with the environment variable `PRE_START_PATH` described above.\n\n\n## Hypercorn configuration\n\nThe image includes a default Gunicorn Python config file at /gunicorn_conf.py.\nIt uses the environment variables declared above to set all the configurations.\n\nYou can override it by including a file in:\n\n* `/app/app/hypercorn_conf.py`\n* `/app/hypercorn_conf.py`\n* `/hypercorn_conf.py`\n\n\u003csmall\u003e* ordered by priority.\u003c/small\u003e\n\n## Development live reload\nThe default program that is run is at `/start.sh`. It does everything described above.\n\nThere's also a version for development with live auto-reload at:\n\n`/start-reload.sh`\n#### Details\nFor development, it's useful to be able to mount the contents of the application code inside of the container as a Docker \"host volume\", to be able to change the code and test it live, without having to build the image every time.\n\nIn that case, it's also useful to run the server with live auto-reload, so that it re-starts automatically at every code change.\n\nThe additional script `/start-reload.sh` runs Hypercorn with 1 `asyncio` worker.\n\nIt is ideal for development.\n\n#### Usage\nFor example, instead of running:\n\n```sh\n$ docker run -d -p 80:80 myimage\n```\nYou could run:\n```sh\n$ docker run -d -p 80:80 -v $(pwd):/app myimage /start-reload.sh\n```\n* `-v $(pwd):/app`: means that the directory `$(pwd)` should be mounted as a volume inside of the container at `/app`.\n* `$(pwd)`: runs pwd (\"print working directory\") and puts it as part of the string.\n* `/start-reload.sh`: adding something (like `/start-reload.sh`) at the end of the command, replaces the default \"command\" with this one. In this case, it replaces the default (`/start.sh`) with the development alternative `/start-reload.sh`.\n\n#### Development live reload - Technical Details\nAs `/start-reload.sh` runs Hypercorn for debug/development purpose it doesn't use hypercorn_config file.\n\nBut these environment variables will work the same as described above:\n\n* `MODULE_NAME`\n* `VARIABLE_NAME`\n* `APP_MODULE`\n* `HOST`\n* `TCP_PORT` (only tcp avaible)\n* `LOG_LEVEL`\n\n\n### Falsy/Truly value\n\nThe included `/hypercorn_conf.py` has some options that accepts boolean value.\nThese are the valid values. Invalid values will raise an exception.\n\nFalsy values (compared after lowered):\n* `\"no\"`\n* `\"n\"`\n* `\"0\"`\n* `\"false\"`\n  \nTruly values (compared after lowered):\n* `\"yes\"`\n* `\"y\"`\n* `\"1\"`\n* `\"true\"`\n\n\n## Python 3.9 support\n\nPython 3.9 is now supported, but some optional packages are not installed due to incompatible Python version.\n\nIncompatible packages:\n* `trio` (`hypercorn[trio]`)\n\n## License\nLicensed under MIT License.\n\nBased on [tiangolo/uvicorn-gunicorn-docker](https://github.com/tiangolo/uvicorn-gunicorn-docker)\n\n[docker tags]: https://hub.docker.com/repository/docker/bynect/hypercorn-fastapi/tags\n[docker repo]: https://hub.docker.com/repository/docker/bynect/hypercorn-fastapi\n[github repo]: https://github.com/bynect/hypercorn-fastapi-docker\n[fastapi site]: https://fastapi.tiangolo.com/\n[hypercorn site]: https://pgjones.gitlab.io/hypercorn/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbynect%2Fhypercorn-fastapi-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbynect%2Fhypercorn-fastapi-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbynect%2Fhypercorn-fastapi-docker/lists"}