Quick Start
Flask

Deploy a Python Flask App

This quickstart guide explains how to deploy a Flask (opens in a new tab) Python application to Koyeb using:

  1. Git-driven deployment to automatically build and deploy a new version of your application each time a change is detected on your branch.
  2. Pre-built containers you can deploy from any public or private registry.

You will need:

You can deploy and preview the Flask application from this guide in seconds by clicking Deploy to Koyeb button:

Deploy to Koyeb (opens in a new tab)

Consult the repository on GitHub (opens in a new tab) to view this example application.

Create the Python Flask app

Get started by creating a basic Python Flask application to deploy on Koyeb.

Alternatively, you can fork the repository on GitHub (opens in a new tab) to get a complete copy of the code. If you fork the repository, then you can skip to section on git-driven deployment on Koyeb.

In your terminal, run the following commands to create the directory that holds the Flask application code:

mkdir example-flask
cd example-flask

In the example-flask folder, create a new virtual environment folder using the following command:

python -m venv venv

For some operating systems, you might need to use the command with python3:

python3 -m venv venv

Virtual environments (opens in a new tab) provide isolation from the system environment allowing each virtual environment to have its own installation directories, dependencies, etc.

Activate and load your virtual environment:

. venv/bin/activate

With your virtual environment active, install Flask, a minimal web framework, and create the requirements.txt file to store the dependencies and versions of each package required to run the application.

pip install flask gunicorn
pip freeze > requirements.txt

At the root of your project, create a new file called app.py to store the Flask application code. In this code snippet, we define a route to handle requests for / and return "Hello from Koyeb" as a response:

app.py
from flask import Flask
app = Flask(__name__)
 
@app.route('/')
def hello_world():
    return 'Hello from Koyeb'
 
 
if __name__ == "__main__":
    app.run()

This example application can run on any modern version of Python. If your application requires a specific Python version, create a runtime.txt file in your repository with the version number. Consult the build with Python page to learn more.

Run the Python Flask app locally

Launch the application locally to test it:

gunicorn app:app

You can now access the application at http://localhost:8000.

Define app commands using a Procfile

To tell Koyeb how to run the application, create a Procfile at the project root directory, and add the command you want to run, prefixed by the web: identifier:

Procfile
web: gunicorn --bind :$PORT app:app

This command includes the --bind :$PORT option to allow the application to dynamically listen to the port specified by the PORT environment variable.

Push the project to GitHub

In the project directory, initialize a new Git repository by running the following command:

git init

This repository is used to version the application code and push changes to a GitHub repository. Run the following commands to commit and push changes to your GitHub repository, replacing the GitHub username and repository name with values from your account and the GitHub repo name:

git add requirements.txt app.py Procfile
git commit -m "Initial commit"
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
git push -u origin main

Replace <YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME> with your GitHub username and repository name.

Deploy to Koyeb using git-driven deployment

To deploy the Python Flask app to Koyeb using the control panel (opens in a new tab), complete these steps:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Choose the GitHub repository and branch containing your application code. Alternatively, enter our public Flask example repository (opens in a new tab) as the Public GitHub repository: https://github.com/koyeb/example-flask.
  4. Name your App and Service. For example, example-python.
  5. Click the Deploy button.

This creates a Koyeb App and Service which builds and deploys your application on Koyeb. You can access your application running on Koyeb by clicking the URL ending with .koyeb.app.

Deploy to Koyeb using a pre-built container

As an alternative to git-driven deployment, you can deploy a pre-built Docker container from any public or private registry. This can be useful if your application needs specific system dependencies or you need more control over how the build is performed.

To dockerize the Python Flask application, create a Dockerfile in your project root directory and add the following to the file:

Dockerfile
FROM python:3-alpine AS builder
 
WORKDIR /app
 
RUN python3 -m venv venv
ENV VIRTUAL_ENV=/app/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
 
COPY requirements.txt .
RUN pip install -r requirements.txt
 
# Stage 2
FROM python:3-alpine AS runner
 
WORKDIR /app
 
COPY --from=builder /app/venv venv
COPY app.py app.py
 
ENV VIRTUAL_ENV=/app/venv
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
ENV FLASK_APP=app/app.py
 
EXPOSE 8080
 
CMD ["gunicorn", "--bind" , ":8080", "--workers", "2", "app:app"]

This Dockerfile provides the minimum requirements to run the Python Flask application. You can easily extend it depending on your needs.

To build and push the Docker image to a registry and deploy it on Koyeb, refer to the page on deploying pre-built container images.

What's next

For more examples of Flask applications deployed on Koyeb, check out these tutorials:

To learn more about the features available for your apps, check out the following documentation:

FastifyGo