Use object storage from FastAPI

An application’s filesystem on Sevalla resets on every deployment, so files that users upload belong in a Sevalla object storage bucket. FastAPI talks to the bucket through its S3-compatible API with boto3, the AWS SDK for Python.

At a glance


Source	The `storefront` project from Deploy a FastAPI application, with boto3, `app/storage.py` and two routes added
Processes	Web process and `Migrate` job, unchanged
Services	PostgreSQL, unchanged; an object storage bucket, `storefront-media`, over the S3 API

Environment variables

This guide adds four variables to the ones in Deploy a FastAPI application. The application doesn’t start without them.

Variable	Required	Available during	Secret	Value
`S3_BUCKET`	Yes	Runtime	No	The bucket name, for example `storefront-media-q8w2e`
`S3_ENDPOINT`	Yes	Runtime	No	The bucket’s S3 endpoint, `https://<account-id>.r2.cloudflarestorage.com`
`S3_ACCESS_KEY_ID`	Yes	Runtime	Yes	The bucket’s access key
`S3_SECRET_ACCESS_KEY`	Yes	Runtime	Yes	The bucket’s secret key

Before you begin

A FastAPI project deployed on Sevalla, as in Deploy FastAPI.

Create a bucket

In the sidebar, click Object storage, then click Create object storage. Enter storefront-media as the Name, choose the Location closest to the application, and click Create object storage. Keep it private: the code in this guide shares each file through a presigned URL that expires.

Add the bucket details to the application

The values come from the bucket’s Settings tab. See Connect with the S3 API for each one.

Variable	Where to find it
`S3_BUCKET`	Bucket name under Details, for example `storefront-media-q8w2e`. It’s not the display name.
`S3_ENDPOINT`	Endpoint under Details, in the form `https://<account-id>.r2.cloudflarestorage.com`
`S3_ACCESS_KEY_ID`	Access key under Access keys
`S3_SECRET_ACCESS_KEY`	Secret key under Access keys

A bucket's Settings tab with the display name, location, bucket name, ID and endpoint, and the access key and secret key

Open the environment variables

In the sidebar, click Applications, then click the application. Click the Environment variables tab.

Add the variables

Click Add environment variables. Add the variables, keep Available during runtime selected, and click Add environment variables.

The variables apply with the next deployment. Add them before you deploy the code: the application doesn’t start without them.

Install boto3

Install boto3 and update requirements.txt:

pip install boto3
pip freeze > requirements.txt

Add the S3 client

Create the client from environment variables. Cloudflare R2, which runs Sevalla’s object storage, uses the region auto:

app/storage.py

import os

import boto3

BUCKET = os.environ["S3_BUCKET"]

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY_ID"],
    aws_secret_access_key=os.environ["S3_SECRET_ACCESS_KEY"],
    region_name="auto",
)

Upload and list files

Add the imports to the top of app/main.py and the two routes to the end. Uploads use FastAPI’s UploadFile, which fastapi[standard] supports. The routes are plain def functions, so FastAPI runs boto3’s blocking calls in a thread pool:

app/main.py

from fastapi import UploadFile

from app.storage import BUCKET, s3


@app.post("/files")
def upload_file(file: UploadFile):
    s3.upload_fileobj(
        file.file,
        BUCKET,
        file.filename,
        ExtraArgs={"ContentType": file.content_type or "application/octet-stream"},
    )
    return {"filename": file.filename}


@app.get("/files")
def list_files():
    response = s3.list_objects_v2(Bucket=BUCKET)
    return [
        {
            "filename": item["Key"],
            "url": s3.generate_presigned_url(
                "get_object",
                Params={"Bucket": BUCKET, "Key": item["Key"]},
                ExpiresIn=3600,
            ),
        }
        for item in response.get("Contents", [])
    ]

Each URL works for 1 hour. list_objects_v2 returns up to 1,000 objects per call; pass ContinuationToken for more. See presigned URLs. For a public bucket, link files on its public domain instead; see public URLs. Commit and push the changes. If Auto-deploy is off, click Deploy now on the application’s Overview tab.

Verify

Upload a file and list the bucket, with your application’s domain:

echo "Hello from Sevalla" > hello.txt
curl -F "file=@hello.txt" https://storefront-x7k2m.sevalla.app/files
curl https://storefront-x7k2m.sevalla.app/files

The first response is {"filename":"hello.txt"}. The second lists hello.txt with a url: open it, and the page reads Hello from Sevalla. In the sidebar, click Object storage, click the bucket, and the Objects tab lists hello.txt. See Manage objects. To check the same from a script, read the file back through its presigned URL, and list the bucket with List objects (listObjectStorageObjectsV3), with BUCKET_ID from Deploy with the API:

curl -s "$(curl -s https://storefront-x7k2m.sevalla.app/files | jq -r '.[0].url')"
curl -s https://api.sevalla.com/v3/object-storage/$BUCKET_ID/objects \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.data[].key'

Hello from Sevalla
hello.txt

Deploy with the API

These calls create the bucket, add its variables and deploy the code, as the dashboard steps on this page do. APP_ID is the application from Deploy with the API in the deploy guide, with auto-deploy on, 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: the application doesn’t start until the variables exist, so the push comes last.

Create the bucket

Create object storage bucket (createObjectStorageV3). Its response is the only one that contains the access key and the secret key, so keep it:

BUCKET=$(curl -s -X POST https://api.sevalla.com/v3/object-storage \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "storefront-media", "location": "weur"}')
BUCKET_ID=$(echo "$BUCKET" | jq -r .id)
S3_BUCKET=$(echo "$BUCKET" | jq -r .bucket_name)
S3_ENDPOINT=$(echo "$BUCKET" | jq -r .endpoint)
S3_ACCESS_KEY_ID=$(echo "$BUCKET" | jq -r .access_key)
S3_SECRET_ACCESS_KEY=$(echo "$BUCKET" | jq -r .secret_key)

location is a hint for where most requests come from: weur (Western Europe) suits an application in Frankfurt, and enam (Eastern North America) one in Ashburn. CLI: sevalla object-storage create --name storefront-media --location weur --json. MCP: sevalla_api_create with createObjectStorageV3 and the same body.

Add the variables

Create environment variable (createEnvironmentVariableV3), once per variable, available during runtime only:

while read -r KEY VALUE; do
  curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/env-vars \
    -H "Authorization: Bearer $SEVALLA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"key\": \"$KEY\", \"value\": \"$VALUE\", \"is_runtime\": true, \"is_buildtime\": false}" \
    | jq -c '{key, is_runtime, is_buildtime}'
done <<EOF
S3_BUCKET $S3_BUCKET
S3_ENDPOINT $S3_ENDPOINT
S3_ACCESS_KEY_ID $S3_ACCESS_KEY_ID
S3_SECRET_ACCESS_KEY $S3_SECRET_ACCESS_KEY
EOF

It prints one line per variable, such as {"key":"S3_BUCKET","is_runtime":true,"is_buildtime":false}. CLI: sevalla apps env-vars create "$APP_ID" --key S3_BUCKET --value "$S3_BUCKET", and the same for the others; the CLI makes them available during build and runtime. MCP: set_environment_variables with all four, runtime true and buildtime false.

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.

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

Use object storage from FastAPI

At a glance

Environment variables

Before you begin

Create a bucket

Add the bucket details to the application

Install boto3

Add the S3 client

Upload and list files

Verify

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create a bucket

​Add the bucket details to the application

​Install boto3

​Add the S3 client

​Upload and list files

​Verify

​Deploy with the API

At a glance

Environment variables

Before you begin

Create a bucket

Add the bucket details to the application

Install boto3

Add the S3 client

Upload and list files

Verify

Deploy with the API