Deploy Flask - Sevalla docs

A Flask project runs on Sevalla as an application built from your Git repository: Nixpacks installs it, Gunicorn serves it in the web process, and a job runs its migrations before each deployment. Its data lives in a Sevalla PostgreSQL database that the application reaches over an internal connection.

Before you begin

A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
Python 3.12 or later on your computer.

Create the project

Create a virtual environment and install Flask, the database extensions, Gunicorn and the PostgreSQL driver:

mkdir storefront && cd storefront
python3 -m venv .venv
source .venv/bin/activate
pip install flask flask-sqlalchemy-lite flask-alembic gunicorn "psycopg[binary]"
mkdir storefront

Package	What it does
`flask-sqlalchemy-lite`	Connects SQLAlchemy to the Flask application and its configuration
`flask-alembic`	Database migrations, as `flask db` commands
`gunicorn`	Production WSGI server for the web process
`psycopg[binary]`	PostgreSQL driver

Keep local files out of the repository:

.gitignore

.venv/
__pycache__/
.env
instance/

Add a model and the extensions:

storefront/models.py

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Model(DeclarativeBase):
    pass

class Item(Model):
    __tablename__ = "item"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]

storefront/extensions.py

from flask_alembic import Alembic
from flask_sqlalchemy_lite import SQLAlchemy

from storefront.models import Model

db = SQLAlchemy()
alembic = Alembic(metadatas=Model.metadata)

Add the application factory. Sevalla’s connection URLs start with postgres://, which SQLAlchemy doesn’t accept, so the code switches the scheme to postgresql+psycopg://:

storefront/__init__.py

import os

import sqlalchemy as sa
from flask import Flask

from storefront.extensions import alembic, db
from storefront.models import Item


def database_url() -> str:
    url = os.environ.get("DB_URL", "sqlite:///storefront.sqlite")
    return url.replace("postgres://", "postgresql+psycopg://", 1)


def create_app() -> Flask:
    app = Flask(__name__)
    app.config["SQLALCHEMY_ENGINES"] = {"default": database_url()}
    # Loads every FLASK_* environment variable, for example FLASK_SECRET_KEY.
    app.config.from_prefixed_env()

    db.init_app(app)
    alembic.init_app(app)

    @app.get("/")
    def index():
        count = db.session.scalar(sa.select(sa.func.count()).select_from(Item))
        return {"items": count}

    return app

DB_URL is the variable Sevalla adds when you connect the database; without it, the project uses SQLite in the instance folder. Generate the first migration and apply it to the local database. Flask-Alembic keeps migrations in storefront/migrations:

flask --app storefront db revision "Create item table"
flask --app storefront db upgrade
flask --app storefront run

Prepare the project for Sevalla

Pin the Python version

Nixpacks, the default build strategy, reads the Python version from .python-version. Nixpacks 1.41 supports Python versions up to 3.13, so pin 3.13:

.python-version

3.13

Set the start command

Create nixpacks.toml in the repository root:

nixpacks.toml

[start]
cmd = "gunicorn 'storefront:create_app()' --bind 0.0.0.0:$PORT --workers 2"

Gunicorn calls the application factory and serves the application. The Flask development server isn’t meant for production.
The web process listens on the port in the PORT environment variable. Sevalla sets PORT to the web process’s port, 8080 by default.
Two Gunicorn workers fit in the smallest size (H1, 0.3 GB of memory). Raise --workers when you choose a larger size.
Migrations don’t run here. A job runs them once per deployment.

List the dependencies

Nixpacks installs requirements.txt with pip:

pip freeze > requirements.txt

Commit everything, including storefront/migrations, and push it to your Git provider:

git init
git add .
git commit -m "Prepare for Sevalla"
git branch -M main
git remote add origin https://github.com/acme/storefront.git
git push -u origin main

Deploy to Sevalla

Create the database

In the sidebar, click Databases, then click Create database. Under Database, choose PostgreSQL and the newest version. Enter orders-db as the Display name, choose a Data center and a Size, then click Create database. See Create a database for every field.

Create the application

In the sidebar, click Applications, then click Create > Application. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch. Under Location, choose the same Data center as the database. Keep the Size at H1 or choose a larger one, then click Create application. The application opens on its Overview tab with the status Not deployed yet: creating an application doesn’t deploy it.

Connect the database

Click the Networking tab. Under Connected services, click Add internal connection. Choose orders-db as the Service, turn on Add environment variables to the application, and click Add internal connection. Sevalla adds DB_URL and the other connection variables to the application. See Connect an application.

Add the environment variables

Click the Environment variables tab, then click Add environment variables. Add FLASK_SECRET_KEY with a random string of 32 characters or more (generate one with python -c "import secrets; print(secrets.token_hex(32))"), keep Available during runtime selected, and click Add environment variables. Flask signs sessions with it.

Create the migration job

Click the Processes tab, then click Create process. Choose Job, enter Migrate as the Name and flask --app storefront db upgrade as the Custom start command. Keep the Start policy at Before deployment and the Resource at H1, then click Create process.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

Turn on auto-deploy

To deploy every push to the branch automatically, click the Settings tab, then click Update auto-deploy in the Auto-deploy section. Turn on Auto-deploy and click Update auto-deploy. See Deployments.

The Create process sheet with Job selected, the Name and Custom start command fields, the Start policy set to Before deployment, and the H1 resource

Verify the deployment

On the Deployments tab, wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running. During the rollout, the deployment’s build log shows Migrate has been successful. If the job fails, the deployment fails and nothing changes for visitors.
Click the domain under the application’s name. The response is {"items":0}, which shows that the application reads the PostgreSQL database.

Deploy changes

With Auto-deploy on, every push to the branch starts a deployment; otherwise, click Deploy now for each change. Each deployment builds the image, runs the Migrate job, then replaces the web process’s instances. For a schema change, run flask --app storefront db revision "<message>" locally and commit the new migration with the code. See Deployments.

Add a custom domain

Add the domain on the application’s Domains tab. Flask doesn’t check the host, so no code change is needed. Custom domains need a web process larger than H1.

Troubleshoot the deployment

Symptom	Cause	Fix
The application or the job crashes with `Can't load plugin: sqlalchemy.dialects:postgres`	The code passes Sevalla’s `postgres://` URL to SQLAlchemy unchanged.	Replace the scheme with `postgresql+psycopg://`, as `database_url()` does.
The deployment fails at `Migrate has failed`	The migration raised an error, or the application can’t reach the database.	Read the job’s output in the build log. Check that the internal connection exists, that `DB_URL` is set, and that `storefront/migrations` is in the repository.
The web process crashes with `Failed to find attribute 'create_app'`	The module in the start command doesn’t match the package with the factory.	Update `[start]` in `nixpacks.toml` to name your package, for example `gunicorn 'app:create_app()'`.
The build fails with `Could not find a version that satisfies the requirement`	The build uses a Python version older than a package supports.	Add `.python-version` with `3.13`.

For more causes, see Troubleshoot builds and deployments. To add caching, background tasks or health checks, see the Flask guides.

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Pin the Python version

​Set the start command

​List the dependencies

​Deploy to Sevalla

​Verify the deployment

​Deploy changes

​Add a custom domain

​Troubleshoot the deployment