bottle_heroku_tutorial: A Python repository from drandreaskrueger

Deploying a Bottle web app on Heroku

This tutorial shows how to set up and deploy a Bottle web app on Heroku. Bottle is a Python micro web framework that's easy to learn and use.

Steps covered in this tutorial:

What you need
Get the sample Bottle app
Deploy the Bottle app on Heroku
Push updates to Heroku

Quickstart

All below steps in one compact batch. Less experienced users: scroll down, to read the details.

sudo apt install git snapd
sudo snap install heroku

git clone https://github.com/drandreaskrueger/bottle_heroku_tutorial.git    # change this to your fork.
cd bottle_heroku_tutorial/

python3 -m venv env                # virtualenv keeps pip installed dependencies local to this project.
source env/bin/activate
pip3 install --upgrade pip bottle

python3 sample_app.py              # test the sample app locally
# open http://localhost:8080

heroku login --interactive  # if not several heroku accounts, browser login easier, drop: --interactive
heroku create bottle-heroku-tutorial-2  # try until you find an unused name, or just use heroku create.

heroku git:remote -a bottle-heroku-tutorial-2          # again the same name
git remote -v

git push heroku master     # watch heroku git server answers - some errors would already be found then!
heroku open

heroku logs --tail           # watch this while browsing https://bottle-heroku-tutorial-2.herokuapp.com
heroku apps:destroy bottle-heroku-tutorial-2 --confirm bottle-heroku-tutorial-2    # and ... it's gone.

Now step by step:

What you need

You need a text editor and a command-line interface like the command prompt in Windows or the Terminal on the Mac.

You also need to install Python and a few libraries, as described next.

Install Python

Install version 3 of Python on your computer if you don't already have it. Visit the Python website to learn more. To download and install it, see http://www.python.org/download/.

When copying the examples in this tutorial, make sure to indent lines exactly as shown. Indentation matters in Python.

Install pip (Python 3.3 or earlier)

After installing Python, install pip, a simple tool for installing and managing Python packages.

Note: If you have Python 3.4 or better, you already have pip. Skip ahead.

Right-click get-pip.py and download the file.
In your command-line interface, navigate to the folder containing the get-pip.py file.
Run the following command:
```
$ python3 get-pip.py
```
Note: In Windows, the prompt is C:\> instead of $.

If you have any trouble, see the pip instructions.

Install Bottle

After installing pip, use the following pip command to download and install Bottle.

$ pip3 install bottle

If you have Python 3.3 or earlier and you installed pip separately, use pip instead of pip3 on the command line.

If you have any problems, see the Bottle instructions.

Install Git

You'll use Git, the popular version control system, to push files to the remote server on Heroku.

Note: If you already have Git, update it to the latest version.

Download and run one of the following installers:

Windows - http://git-scm.com/download/win
Mac - http://git-scm.com/download/mac

Get the sample Bottle app

Because this isn't a Bottle tutorial, a set of starter files is provided. Click the following link to download it from Github:

https://github.com/drandreaskrueger/bottle_heroku_tutorial/archive/master.zip

Bottle basics

To keep things simple, the sample app simulates an API request that gets the name and role of a user.

Navigate to the bottle_heroku_tutorial folder in a file browser. The sample_app.py file is the app's nerve center. Open it in a text editor to take a look. Here's a link to the file in this repository:

sample_app.py

The file consist of routes that map HTTP requests to functions. The return value of each function is sent in the HTTP response. To learn more, see Request Routing in the Bottle docs.

Routes typically specify templates to render for the response. To learn more, see Templates in the Bottle docs.

The sample_app.py file calls the framework's run() function to run the app on a local web server or on Heroku:

if "heroku" in os.environ.get('PYTHONHOME', ''):
    run(host="0.0.0.0", port=int(os.environ.get("PORT", 5000)))
else:
    run(host='localhost', port=8080, debug=True)

The sample app checks for the PYTHONHOME environment variable to decide which statement to run. On heroku it reads '/app/.heroku/python', while (e.g. on two of my machines) it might not even be set at all.

The Bottle framework includes a built-in development server that you can use to test your changes locally before deploying them to a remote server.

You can run the sample app locally as follows:

In your command-line interface, navigate to the app folder that contains the sample_app.py file.
Run the following command to start the local server:
```
$ python3 sample_app.py
```
In a browser, go to http://localhost:8080/home.

You should see the sample app's admittedly plain home page.
Run some tests.

Try clicking the link on the home page.
When you're done, switch to your command-line interface and press Ctrl+C to shut down the server.

Deploy the Bottle app on Heroku

Deploying a Bottle app for the first time consists of the following steps:

Get a free Heroku account
Create a remote Git repo for your app on Heroku
Create a local Git repo
Prepare the app files for deployment
Push the app to Heroku

Get a free Heroku account

If you don't already have an Heroku account, you can sign up for a free one.

Note: If you already have an account and have installed the Heroku Command Line Interface (CLI), you can skip this section.

Go to https://signup.heroku.com/dc, then enter your information, pick Python as your primary development language, then click Create Free Account.
Check your email to confirm your account. When prompted, set up a password.

After setting up a password, you'll be taken to a welcome page.
Install the Heroku Command Line Interface. To download and install it, see Heroku CLI in the Heroku docs.

As the doc suggests, you should login at the command line immediately after installing the tool.

Create a remote Git repo for your app on Heroku

After you push your app to the repo, Heroku will serve the app from there.

If not already done, login to Heroku in your command-line interface:
```
$ heroku login
```
Run the following command:
```
$ heroku create your-app-name
```
Change "your-app-name" to whatever you want to name your app. You can expect that common names like “my-app” or “tutorial” will already be taken. You can omit the name and let Heroku generate a random name that you can change it later. Example:
```
$ heroku create
```
Example response:
```
Creating app... done, ⬢ fast-sierra-15737
https://fast-sierra-15737.herokuapp.com/ | https://git.heroku.com/fast-sierra-15737.git
```

This is a one-time-only requirement. Heroku creates a remote git repository that you'll link to a local Git repo in the next section. This setup will let you use a simple git push command to deploy your app to the server.

Create a local Git repo

Before you start, make sure you installed Git. See Install Git above for instructions.

In your command-line interface, navigate to the folder that contains the files of your Bottle app.

If you copied the sample app, it should be the folder that contains the sample_app.py file.
Run the following 3 commands one after the other:
```
$ git init
$ git add .
$ git commit -m "my first commit"
```
This creates a local Git repository and adds you files to it. You'll connect this local repo to a remote repository on Heroku in the next step.
Make sure you're logged in to Heroku ($ heroku login), then run the following command to set your Heroku app repo as the remote repo of your local repo:
```
$ heroku git:remote -a your-app-name
```
Important: Change "your-app-name" to whatever is the name of your app. Example:
```
$ heroku git:remote -a fast-sierra-15737
```
To verify you set the remote repo, run:
```
$ git remote -v
```

Prepare the app files for deployment

When deploying, the following configuration files need to be included in the web app's root directory:

Procfile
runtime.txt
requirements.txt

In a text editor, create a file named Procfile and make sure it contains the following line:
```
web: python sample_app.py
```
A Procfile lists the app's process types and the commands to start each process. The Bottle app runs a single web process, which is started by executing the python sample_app.py command.
Create a file named runtime.txt and make sure it contains the following line, adjusted for your version number:
```
python-3.7.7
```
The runtime.txt file tells Heroku what Python version to use for your app. The setting ensures Heroku runs your app in the same runtime environment you used locally to develop and test the app.

To find out the version you're using locally, run the following command at the command line:
```
$ python3 --version
```
Create a file named requirements.txt and make sure it lists the following libraries:
```
bottle==0.12.18
requests==2.23.0
```
The file lists all the external libraries the app needs to run. Update the version number of each library, if necessary. To find out the version, run the following commands:
```
$ pip3 show bottle
```
or
```
$ pip3 show requests
```

Add the new config files to your local repo:

$ git add .
$ git commit -a -m "Add config files"

Push the app to Heroku

In this step, you deploy the app to Heroku for the first time.

If not already done, login to Heroku and enter your Heroku email and password when prompted:
```
$ heroku login
```
Deploy the app:
```
$ git push heroku master
```
The command uploads the app files to the remote git repository on Heroku. Heroku then builds and deploys the app.
Set the following APP_LOCATION environment variable in Heroku:

NOT NEEDED if using the trick if "heroku" in os.environ.get('PYTHONHOME', ''): instead.
```
$ heroku config:set APP_LOCATION=heroku
```
This is a one-time-only requirement. The code in sample_app.py has two different run statements: one for the local server and one for the Heroku server. At runtime, the app checks for the APP_LOCATION environment variable to decide which one to run:
```
if os.environ.get('APP_LOCATION') == 'heroku':
    run(host="0.0.0.0", port=int(os.environ.get("PORT", 5000)))
else:
    run(host='localhost', port=8080, debug=True)
```
Open and test the app in a browser:
```
$ heroku open
```

If something goes wrong, go back to your command-line interface and enter heroku logs --tail. Check the entries for clues of what went wrong.

Bookmark the URL of your app.

Push updates to Heroku

You can start tweaking or adding to the app. See the Bottle tutorial. Test your changes locally before pushing the changes to Heroku, as described next.

Note: If you make changes to the sample_app.py file while the local server is running, you have to stop and restart the server to see the changes. You don't have to restart the server if you make changes to static files like the templates or css. Just refresh the page in the browser.

To push updates to Heroku

In your command-line interface, navigate to your app folder.
Commit all the changes in Git:
```
$ git commit -a -m "Various updates"
```
If not already done, log in to Heroku and enter your Heroku email and password when prompted:
```
$ heroku login
```
Push the files:
```
$ git push heroku master
```
Open and test the app in a browser.
```
$ heroku open
```