lkananen / fastapi_heroku_demo

Docker containerized FastAPI server demo running on Heroku.

FastAPI demo

Docker containered FastAPI server running on Heroku.

Table of Contents

• FastAPI demo
  • Table of Contents
  • Directory structure
  • Example website
  • Architecture
  • Setup
    • Local deployment
    • First time deployment
    • Automatic deployment
      • Secrets
• Additional details
  • Always on application
  • Heroku debug commands
  • Additional links
• Licence

Directory structure

• /.github/workflows Deployment pipeline used by GitHub Actions.
• /docs Documentation files.
• /source Source files and environment configurations for the web server.
  • /source/app Web server application. FastAPI docs and URIs.
  • /source/docker-compose.yml Wer server Docker container compose definition.
  • /source/Dockerfile Web server Docker container definition.
  • /source/entry.sh Web server startup script run in the Docker container.
  • /source/requirements.txt Web server required packages.
• Procfile Heroku process type declaration for the web server startup.
• heroku.yml Heroku process type declaration for the web server startup.

Example website

Demo website starts based on the defined application name:
link

FastAPI automatically creates documentation for the web application. It is accessible as a docs website in Swagger format. Example of this below:

Architecture

Deployment pipeline architecture: Commits trigger GitHub actions to push changes to Heroku. Changes to Heroku trigger a Docker Compose build that creates a new version of the containerized FastAPI.

Setup

Following instructions setup the demo and there are multiple ways to do it.

1. Local deployment: relies on Python environment and a Procfile, sets up everything from this repository as a local web server.
2. Manual Heroku deployment: First time setup requires a Heroku application creation. The webserver stack can be defined in two ways: As a Python application through the Procfile or as an containerized application through Docker Compose definition. The compose application requires a stack configuration change described below in the commands.
3. Automatic Heroku deployment: Requires first manual setup first time and setting up the required secrets. Configures an automatic deployment pipeline that runs Git commits through GitHub repository's GitHub Actions. The pipeline workflow pushes the changes to Heroku application repository and initiates a reload of the web server application. The application is built using a Docker Compose definition running a FastAPI application in a Docker container.

Local deployment

Running following commands sets up local server.

git clone https://github.com/lkananen/fastapi_demosite.git

pip install -r source/requirements.txt

#heroku login                       # Not completely neccessary
heroku local -f Procfile            # Starts the server
heroku open

First time deployment

Heroku application creation is required on the first time.
Note! Automated pipeline requires app creation and stack definition.

Following commands create example-app-name Heroku application. After creation GitHub Actions can be attached to the application in the Heroku portal for automated deployments.

git clone https://github.com/lkananen/fastapi_demosite.git

# Heroku setup
heroku login
heroku apps:create example-app-name --region eu

# Heroku build requirements
heroku buildpacks:set heroku/python --app example-app-name

# Heroku needs to know that app is in a Docker container
heroku stack:set container --app example-app-name

# Manual Heroku deployment
git push heroku main
heroku ps:scale web=1           # sets dynos

Automatic deployment

Note! Automated pipeline requires stack definition and app creation from first time deployment AND defining the secrets.

Based on GitHub Actions and Heroku deployment configuration files. Commit triggers dependency check and deployment to Heroku. See secrets on the required setup on Heroku secrets.
Also optionally, Heroku can be configured to connect to GitHub to allow manual and automatic deployments based on the commits. Heroku deployment pipeline does not support build checks or other actions on the free tier.

Secrets

Note! Required by GitHub Actions.

GitHub Action uses secrets to push changes to Heroku. Following secrets are required to be added to repository's secrets in the repository settings:

1. HEROKU_API_KEY
   • Can be found in:
     Heroku -> Profile -> Account settings -> API key
2. HEROKU_APP_NAME
   • Name of the Heroku application.
   • Must be unique.
3. HEROKU_EMAIL
   • Email that you use with Heroku.

Additional details

Relevant details for further development, debugging and interaction with the application.

Always on application

Heroku application goes to sleep after 30 minutes of inactivity. For example, Kaffeine application can be used to pings the app so that it stays active:
http://kaffeine.herokuapp.com/

Deactivation link to Kaffeine:
http://kaffeine.herokuapp.com/#decaf

Heroku debug commands

Useful command for Heroku debugging:

heroku open                     # Open the default app in browser
heroku logs --tail              # Recent logs, Heroku stores 1500 lines
heroku run bash                 # Connect to dyno
heroku ps:exec                  # SSH to dyno
heroku ps                       # Info on dyno

Additional links

• Full stack project template
• Project templates

Licence

MIT License

Copyright (c) 2022 Lauri Kananen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.