Heroku Brew

A step-by-step tutorial on creating a web application with Streamlit, building a Docker image with GitHub Actions, and hosting on Heroku.

May 19, 2018 Try to use this command: brew tap heroku/brew && brew install heroku For me it is working now. Use sudo snap install -classic heroku. Sudo snap install -classic heroku. Download the installer (opens new window) Also available via Homebrew: brew tap heroku/brew && brew install heroku. Download the appropriate installer for your Windows installation: 64-bit installer (opens new window) 32-bit installer (opens new window) #.

This tutorial is meant to act as a guide for deployingStreamlit applications onHeroku usingDocker andGitHub Actions.As a data scientist, Streamlit offers the simplest route from analysis to application by providing an API to create an interactive UI in a normal Python script.We’ll see more about this in the example later on, but there are many examples in theirgallery.

Once the application is built and running locally, we just need to package it up using Docker and deploy to Heroku.In addition, I have included a step to use GitHub Actions to build and push the Docker image, saving my local computer some computation and time.Below, I walk through this process, step-by-step.

Create a Streamlit application

Introduction to Streamlit

Streamlit is built for data scientists and analysts.Instead of building applications like many software engineers, we often write scripts that collect and clean data, visualize the data, design and train models, etc.While it is possible to process the output of these scripts into interactive applications that requires a substantial amount of work and maintenance.Instead, Streamlit offers a clever API: just “print” the plots, text, etc. and accept user input to variables.Streamlit then handles all of the UI design, reacts to the user, and presents interactive widgets.If this seems appealing to you, I would recommend looking through theirwebsite,gallery, anddocumentation to see examples and get guidance on implementation.

Example: text-summarizing application

As an example of using Streamlit, I built an application that summarizes text.

First things first, it is generally a good idea (and will be necessary for using Docker) to create a virtual environment for this project and installing‘summa’ (the library that I used to summarize the text) and‘streamlit’.

Below is the entire Streamlit application!I won’t provide much explanation because I don’t think much is required - in most cases, it is very obvious what Streamlit is doing.Using the st.title() function, a title is placed at the top of the app.Then some text is collected from the user by the st.text_area() function - this text is saved as a string to input_sent.The summarization ratio is obtained using a slider with the st.slider() function.Finally, the text is summarized using the ‘summa’ library and printed to the application using st.write() in a for-loop.

The application can be run locally with the following command and going tohttp://localhost:8501 in your browser.

The initial blank application is shown below followed by an example of summarizing the opening scene toMonty Python and the Holy Grail (text source).

Build a Dockerfile

The next step is to construct a file called “Dockerfile” that provide instructions to produce a Docker image with the running application.Below is the complete Dockerfile and I have provided a brief explanation afterwards.

Heroku Repo

The FROM python:3.9 at the beginning of the file means that this Dockerfile builds on-top of another that has Python 3.9 already installed and configured.In order to use this, you must have aDockerhub account and link it to the Docker application on you computer.Here is the link to the Python Dockerhub page:https://hub.docker.com/_/python.

Next, the EXPOSE 8501 command exposes port 8501 from the Docker image so that it can be reached when the image is run.

All of the commands from WORKDIR /app to COPY . . set-up of the Docker environment and create the virtual environment. I’m no expert in Docker, so the details are lost on me, but I think the overall objective is clear from the statements.

Finally, CMD streamlit run app.py declares that the Docker image should run streamlit run app.py and exit when it finishes.

With the Dockerfile in place, the Docker image can be built and run.

Going to the samehttp://localhost:8501, you should again see the application.

Connect and publish to Heroku

Setting up Heroku

The next step is to deploy the application on the World Wide Web usingHeroku.In order to do so, you will need to create an account - there is a free tier for hobbyists that will be sufficient.

Then the command line interface (CLI) for interfacing with Heroku from your computer must be installed.Full instructions can be foundhere; I use a Mac, so I used the Homebrew option.

With a Heroku account created and the CLI installed, the next step is to login with the CLI.The command heroku login will open a login window in your browser.

Finally, we can create a Heroku app by running heroku create while within the project directory.

Deploying a Heroku app

The following steps deploy the Streamlit app to Heroku using their Docker registry.You can find the full documentationhere; specifically, I used theContainer Registry option.

We need to make one change to the Dockerfile in order to deploy on Heroku.As documentedhere, the port to the app must be set to the variable $PORT.This is accomplished using the --server.port flag for the streamlit command, resulting in the following change to the Dockerfile.

Heroku Reddit

From there, deploying using the Docker registry in Heroku is routine.First, you must log in to the registry using the command below.

Then, the following command builds the Docker image and pushes it to the Heroku registry.

The app is then deployed to the web as follows.

After allowing a few minutes for Heroku to work its magic, you can open the app on the web from the command line or in yourHeroku Dashboard.

Set up deployment with GitHub Actions

You can stop here if the above pipeline works for you, but I wanted to automate the deployment pipeline and move the computation of my computer.Therefore, I turned toGitHub Actions to build the Docker image and push to Heroku’s registry when I push changes to the remote repository.(Obviously, to use GitHub Actions, you will need to have the project under git source control and an accompanying GitHub repo.)

Below is the GitHub Actions workflow file; you will need to place this in the subdirectory ./.github/workflows/CI.yml.It is a YAML file with a single job with multiple steps that perform the same operations using the Heroku command line we preformed above.Additional details are available below.Once you have the YAML file and the authorization secret setup for the repo (explained below), pushing the changes to GitHub should result in the building and deployment of the app.

Explanation of the GitHub Action workflow

The name of the workflow is stated first, followed by a description of when the workflow should be run. In this case, I have it set to run when there are pushes to the master branch. More details and options can be found in the documentation onEvents that trigger workflows.

This next chunk is fairly standard for simple workflows.To begin, it declares a new job (workflows can have multiple jobs that run in parallel) and is set to run on a “runner” server using Ubuntu.Then, the first step is to use the actions/checkout@v1 action to checkout the current repository.This action is provided by GitHub and must be run in order to use the files in the repo.

The following steps perform the same commands we just ran on our local machine to login to the Heroku container registry, build the Docker image, and deploy it to the web.The only difference is the declaration and use of the HEROKU_API_KEY variable.This is declared in the YAML structure under the heading env.To actually set it to a key to allow access to Heroku, we must useGitHub secrets - do NOT put your login information the workflow file in plain text.To add the key to secrets, run the following command on your computer to get an authorization key.

Then, put the key in a secret by going to the “Settings” tab of your GitHub repo, navigating to “Secrets” in the bar on the left, and clicking “New repository secret.”I named the secret key HEROKU_API_KEY to match the variable name used by Heroku, though you can change it to whatever makes sense to you, just make sure to also change the workflow file.

Conclusion

This simple project was amazing to me - the ability to build a good application in ~20 lines of code and deploy it to the web for free with such ease really speaks to the incredible state of open source tooling.So far I have deployed two Streamlit apps currently running on Heroku: theText Summarization (source) application demonstrated here and aSuduko Solver (source) that uses linear programming to find the solution.I look forward to using this setup as a starting point for more complex apps in the future.

Heroku is a Platform-as-a-Service (PaaS) that simplifies deploying your apps online.

Heroku Revert

Installation

Assuming you have a Heroku account (sign up if you don't), let's install the Heroku Client for the command-line using Homebrew.

The formula might not have the latest version of the Heroku Client, which is updated pretty often. Let's update it now:

Don't be afraid to run heroku update every now and then to always have the most recent version.

Setup

If this is a new account, and since you don't already have a public SSH key in your ~/.ssh directory, it will offer to create one for you. It will also upload the key to your Heroku account, which will allow you to deploy apps from this computer.

If it didn't offer create the SSH key for you (i.e. your Heroku account already has SSH keys associated with it), you can do so manually by running:

Keep the default file name and skip the passphrase by just hitting Enter both times. Then, add the key to your Heroku account:

Usage

Once your keys are in place and you are authorized, you're ready to deploy apps. Heroku has a getting started guide, which has all the information you need (the one linked here is for Python, but there is one for every popular language). Heroku uses Git to push code for deployment, so make sure your app is under Git version control.

Heroku Brew Bar

A cheat sheet for deployment:

Heroku Brewster

The Heroku Dev Center is where you will find more information.