Add Flask health checks

Health checks are HTTP requests that Sevalla sends to each instance of the web process. The readiness probe decides when an instance gets traffic: during a deployment, new instances receive requests only once it passes. The liveness probe restarts an instance that stops responding. A Flask application needs two endpoints for them, one that checks the database and one that only checks that the application answers.

At a glance


Source	The `storefront` project from Deploy a Flask application, with `/healthz` and `/livez` added
Processes	Web process and `Migrate` job, unchanged
Health check	`GET /healthz` returns `200` when the database answers (readiness probe); `GET /livez` returns `200` (liveness probe, 10-second initial delay); both with a 1-second timeout

Environment variables

This guide adds no variables. The application uses the ones in Deploy a Flask application.

Before you begin

The storefront project from Deploy Flask, deployed on Sevalla. This guide replaces its app/__init__.py.

Add the endpoints

Replace app/__init__.py with this version, which adds /healthz and /livez to the application factory:

app/__init__.py

import os

import sqlalchemy as sa
from flask import Flask, request

from app.extensions import alembic, db
from app.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("/items")
    def list_items():
        items = db.session.scalars(sa.select(Item).order_by(Item.id))
        return [{"id": item.id, "name": item.name} for item in items]

    @app.post("/items")
    def create_item():
        item = Item(name=request.json["name"])
        db.session.add(item)
        db.session.commit()
        return {"id": item.id, "name": item.name}, 201

    @app.get("/healthz")
    def healthz():
        try:
            db.session.execute(sa.text("SELECT 1"))
        except sa.exc.SQLAlchemyError:
            return {"status": "database unavailable"}, 503
        return {"status": "ok"}

    @app.get("/livez")
    def livez():
        return {"status": "ok"}

    return app

/healthz returns 200 when the database answers a query and 503 with {"status":"database unavailable"} when it doesn’t. Use it for readiness: an instance that can’t reach the database gets no traffic.
/livez returns 200 whenever the application runs. Use it for liveness, so that a database outage doesn’t restart every instance.

Ingot starts Gunicorn with 4 threads per worker process, so one slow request doesn’t hold up the probes. Add more checks to /healthz for each service the application can’t work without, such as cache.get("health") for a Redis cache. Commit and push the changes, and wait for the deployment to finish before you turn on the probes:

git add .
git commit -m "Add health checks"
git push

If Auto-deploy is off, click Deploy now on the application’s Overview tab.

Turn on the health checks

Open the web process

On the application’s Processes tab, click ⋯ on the Web process, then click Update process.

Turn on the readiness probe

Under Health checks, turn on Readiness probe and set the Path to /healthz. Keep the Port at the web process’s port, 8080 unless you changed it.

Turn on the liveness probe

Turn on Liveness probe, set the Path to /livez, and set the Initial delay to 10 seconds, so a slow start doesn’t count as a failure.

Save and deploy

Click Update process, then click Deploy in the undeployed changes bar at the bottom of the page.

The sheet for updating the web process, with its start command, resource, scaling and the Health checks section with the readiness probe on

A probe passes when the path answers with a status from 200 to 399 within the timeout (1 second by default). Only the web process has health checks. See Health checks for every probe setting and its default.

Verify

Request the endpoint through your domain. The command prints the body, which Flask ends with a newline, then the status code:
curl -s -w "\n%{http_code}\n" https://storefront-x7k2m.sevalla.app/healthz
{"status":"ok"} 200
On the Deployments tab, the deployment that turned on the probes reaches Deployed: its new instance passed the readiness probe before it took traffic.

To read the probes back, use Get process (getProcessV3) with APP_ID and WEB_ID from Deploy with the API:

curl -s https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -c '[.readiness_probe, .liveness_probe] | map({path: .httpGet.path, initialDelaySeconds, timeoutSeconds})'

[{"path":"/healthz","initialDelaySeconds":0,"timeoutSeconds":1},{"path":"/livez","initialDelaySeconds":10,"timeoutSeconds":1}]

The CLI shows the process with sevalla apps processes get "$WEB_ID" --app-id "$APP_ID" --json, and the MCP server with get_application.

If the deployment doesn’t finish, click App health on the Overview tab to see each instance’s status. An instance that fails the readiness probe shows Unready: request the path yourself and check that it returns 200, and that the Port matches the port Gunicorn listens on.

Deploy with the API

These calls deploy the endpoints, then turn on the probes, as the steps on this page do. APP_ID and WEB_ID, the web process, come from Deploy with the API in the deploy guide, which also turned on auto-deploy, and SEVALLA_API_KEY holds the same API key. Commit the code from this page first, without pushing it, and run the commands in the project folder.

Push and find the deployment

Push the commit. Auto-deploy starts a deployment of it, and List deployments (listDeploymentsV3), newest first, returns it once it exists:

git push
COMMIT=$(git rev-parse HEAD)
for i in $(seq 1 60); do
  DEPLOYMENT_ID=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" \
    | jq -r --arg commit "$COMMIT" 'first(.data[]? | select(.commit_sha == $commit) | .id) // empty')
  [ -n "$DEPLOYMENT_ID" ] && break
  sleep 5
done

With auto-deploy off, start it with Trigger deployment (triggerDeploymentV3) instead. CLI: sevalla apps deployments list --app-id "$APP_ID". MCP: list_deployments.

Wait for the deployment

Get deployment (getDeploymentV3) until status is success or failed:

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

It prints success when the deployment finishes, or failed; after 30 minutes without either, it prints the status it last read. CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment, then get_deployment_logs if it failed.

Turn on the health checks

Update process (updateProcessV3) on the web process. Send every probe field, timeoutSeconds included: a probe set through the API without it waits up to 120 seconds for an answer, not the dashboard’s 1 second. The values are the dashboard’s defaults, with the paths from this page and a 10-second initial delay for the liveness probe:

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -c '{readiness: .readiness_probe.httpGet.path, liveness: .liveness_probe.httpGet.path, timeout: .readiness_probe.timeoutSeconds}'
{
  "readiness_probe": {
    "httpGet": {"path": "/healthz", "port": 8080, "scheme": "HTTP"},
    "initialDelaySeconds": 0,
    "periodSeconds": 10,
    "timeoutSeconds": 1,
    "successThreshold": 1,
    "failureThreshold": 3
  },
  "liveness_probe": {
    "httpGet": {"path": "/livez", "port": 8080, "scheme": "HTTP"},
    "initialDelaySeconds": 10,
    "periodSeconds": 10,
    "timeoutSeconds": 1,
    "successThreshold": 1,
    "failureThreshold": 3
  }
}
EOF

It prints {"readiness":"/healthz","liveness":"/livez","timeout":1}. CLI: not available. MCP: sevalla_api_update with updateProcessV3 and the same body.

Deploy the health checks

The probes apply at the next deployment. Trigger deployment (triggerDeploymentV3) with is_restart reuses the last build:

DEPLOYMENT_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/deployments \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_restart": true}' | jq -r .id)

CLI: sevalla apps deployments trigger "$APP_ID" --restart. MCP: trigger_deployment with restart set to true.

Wait for the deployment

Get deployment (getDeploymentV3) until status is success or failed:

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

success means the new instance passed the readiness probe. CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Then run the checks in Verify, with the domain from List application domains (listApplicationDomainsV3) as in the deploy guide.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Add Flask health checks

At a glance

Environment variables

Before you begin

Add the endpoints

Turn on the health checks

Verify

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Add the endpoints

​Turn on the health checks

​Verify

​Deploy with the API

At a glance

Environment variables

Before you begin

Add the endpoints

Turn on the health checks

Verify

Deploy with the API