Flask Deploying on Heroku

Heroku is a cloud platform that hosts web applications. You push your Flask code to Heroku using Git, and Heroku builds and runs it automatically. No server configuration required — Heroku manages the infrastructure so you focus on your app.

How Heroku Works

Your computer                   Heroku
    │                               │
git push heroku main  ──────▶  Detects Python app
                                    │
                               Installs requirements.txt
                                    │
                               Reads Procfile (startup command)
                                    │
                               Starts your Flask app
                                    │
                               Your app is live at
                               https://yourapp.herokuapp.com

Prerequisites

• A Heroku account (free tier available at heroku.com)
• Heroku CLI installed on your computer
• Git initialized in your project folder
• Your Flask app working locally

Install the Heroku CLI

Download and install from the Heroku website, then log in:

heroku login

A browser window opens for authentication. After logging in, the CLI stores your credentials.

Required Files for Heroku

1. Procfile

A Procfile (no extension) tells Heroku how to start your app. Create it in the project root:

web: gunicorn run:app

run:app means: in run.py, use the object named app. Heroku uses Gunicorn as the production WSGI server instead of Flask's development server.

2. Install Gunicorn

pip install gunicorn
pip freeze > requirements.txt

3. runtime.txt (Optional)

Specify the Python version:

python-3.11.8

Project Files Needed on Heroku

myapp/
├── run.py              ← entry point
├── requirements.txt    ← all dependencies
├── Procfile            ← startup command
├── runtime.txt         ← python version
└── app/
    └── ...

Deploying to Heroku

# Step 1: Create a new Heroku app
heroku create my-flask-app

# Step 2: Add config variables (replaces .env)
heroku config:set SECRET_KEY=your-super-secret-key
heroku config:set FLASK_ENV=production

# Step 3: Add a PostgreSQL database (free tier)
heroku addons:create heroku-postgresql:mini

# Step 4: Push your code
git add .
git commit -m "Deploy to Heroku"
git push heroku main

# Step 5: Run database migrations
heroku run flask db upgrade

# Step 6: Open your app
heroku open

Environment Variables on Heroku

Heroku uses config vars instead of .env files. These are securely stored and injected as environment variables when your app starts:

# Set a variable
heroku config:set DATABASE_URL=postgresql://...

# View all variables
heroku config

# Remove a variable
heroku config:unset OLD_VARIABLE

Your Flask app reads these with os.environ.get('SECRET_KEY') — the same code that reads your local .env file. No code changes needed.

Database on Heroku

Heroku PostgreSQL sets a DATABASE_URL config var automatically when you add the addon. Update your config to read it:

import os

class ProductionConfig(Config):
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL', '').replace(
        'postgres://', 'postgresql://', 1
    )

Heroku sets DATABASE_URL with a postgres:// prefix, but SQLAlchemy requires postgresql://. The .replace() call fixes this difference.

Viewing Logs

heroku logs --tail

This streams live log output from your app. When something goes wrong in production, logs show the error and stack trace.

Common Heroku Deployment Errors

Summary

Deploying a Flask app to Heroku takes five steps: create a Procfile pointing to Gunicorn, freeze your dependencies into requirements.txt, create a Heroku app, set config vars, and push with git push heroku main. Heroku handles the server, SSL certificate, and scaling. Use heroku logs --tail to debug production issues and heroku config:set to manage secrets safely.