Getting Started on Heroku with Clojure Introduction. This tutorial will have you deploying a Clojure app in minutes. Hang on for a few more minutes to learn how it all works, so you can make the most out of Heroku. Heroku is a Platform-as-a-Service (PaaS) that simplifies deploying your apps online. Assuming you have a Heroku account (sign up if you don't), let's install the Heroku Client for the command-line using Homebrew. Brew install heroku/brew/heroku The formula might not have the latest version of the Heroku Client, which is updated pretty often. 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) #.
- tap 'homebrew/bundle'
- tap 'homebrew/cask-fonts'
- tap 'jesseduffield/lazygit'
- tap 'px4/px4'
- brew 'dfu-programmer'
- brew 'ffmpeg'
- brew 'gist'
- brew 'hugo'
- brew 'mackup'
- brew 'neovim'
- brew 'nodebrew'
- brew 'rsync'
- brew 'wget'
- brew 'youtube-dl'
- brew 'jesseduffield/lazygit/lazygit'
- brew 'px4/px4/gcc-arm-none-eabi'
- cask 'adobe-creative-cloud'
- cask 'alfred'
- cask 'bartender'
- cask 'boostnote'
- cask 'docker'
- cask 'easycrop'
- cask 'font-hack-nerd-font'
- cask 'google-chrome'
- cask 'hammerspoon'
- cask 'imageoptim'
- cask 'iterm2'
- cask 'kindle'
- cask 'slack'
- cask 'spotify'
- cask 'tripmode'
- cask 'virtualbox'
- mas 'Affinity Designer', id: 824171161
- mas 'BetterSnapTool', id: 417375580
- mas 'CLCL Lite', id: 495511246
- mas 'DaisyDisk', id: 411643860
- mas 'Fotor Photo Editor', id: 503039729
- mas 'HazeOver', id: 430798174
- mas 'Jump Desktop', id: 524141863
- mas 'LINE', id: 539883307
- mas 'Mini Calendar', id: 1088779979
- mas 'OmniFocus', id: 1346203938
- mas 'Pages', id: 409201541
- mas 'Pixave', id: 924891282
- mas 'Reeder', id: 880001334
- mas 'TaskPaper', id: 1090940630
- mas 'ToothFairy', id: 1191449274
- mas 'Tweetbot', id: 557168941
- mas 'Ulysses', id: 1225570693
- mas 'Yoink', id: 457622435
A step-by-step tutorial on creating a web application with Streamlit, building a Docker image with GitHub Actions, and hosting on Heroku.
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.
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.
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.
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.
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.
Heroku Brew Recipe
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/[email protected] 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.
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 freeFrostwire. 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.