Store Django media in object storage

Django saves uploaded files (media) to the local filesystem by default, and Sevalla resets an application’s filesystem on every deployment. With django-storages, Django saves them in a Sevalla object storage bucket instead, through its S3-compatible API, so every instance and every deployment sees the same files.

At a glance

This guide adds to the application from Deploy a Django application:


Services	A Sevalla object storage bucket, `storefront-media`, through its S3-compatible API

Environment variables

Variable	Required	Available during	Secret	Value
`S3_BUCKET`	Yes	Build and runtime	No	The bucket’s Bucket name, such as `storefront-media-q8w2e`
`S3_ENDPOINT`	Yes	Build and runtime	No	The bucket’s Endpoint: `https://<account-id>.r2.cloudflarestorage.com`
`S3_ACCESS_KEY_ID`	Yes	Build and runtime	Yes	The bucket’s Access key
`S3_SECRET_ACCESS_KEY`	Yes	Build and runtime	Yes	The bucket’s Secret key
`S3_PUBLIC_DOMAIN`	Public buckets only	Build and runtime	No	The bucket’s Public domain, such as `storefront-media-q8w2e.sevalla.storage`

With Ingot, the build needs every variable, because collectstatic loads the settings, which read them without a default. The deploy guide lists the other variables.

Before you begin

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

Create a bucket

Create the 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.

Decide who can read the files

Keep the bucket private to serve each file through a link that expires. To serve files to anyone with a permanent URL, click the bucket’s Settings tab, click Enable public access under Public access, then click Enable public access in the dialog.

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
`S3_PUBLIC_DOMAIN`	Public buckets only: Public domain under Public access, for example `storefront-media-q8w2e.sevalla.storage`

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 and Available during buildtime selected, and click Add environment variables.

The build needs the variables too: Ingot runs collectstatic during the build, which loads the settings, and the settings read the variables without a default. They apply with the next deployment, so add them before you deploy the new settings. If the application builds from your own Dockerfile, its build doesn’t read them: Sevalla passes build-time variables to a Dockerfile as build arguments, which the Dockerfile doesn’t declare, so the bucket’s keys stay out of the image. Without the variables, the build stops with ImproperlyConfigured: Set the S3_BUCKET environment variable. Give collectstatic placeholders for them, next to the placeholder SECRET_KEY. collectstatic loads the settings but doesn’t touch the bucket:

Dockerfile

RUN SECRET_KEY=collectstatic-placeholder \
    S3_BUCKET=collectstatic-placeholder \
    S3_ENDPOINT=https://collectstatic.invalid \
    S3_ACCESS_KEY_ID=collectstatic-placeholder \
    S3_SECRET_ACCESS_KEY=collectstatic-placeholder \
    python manage.py collectstatic --noinput \
    && python -m compileall -q .

Install django-storages

Install django-storages 1.14 with its S3 extra, which adds boto3, and update requirements.txt:

pip install "django-storages[s3]"
pip freeze > requirements.txt

Configure the storage

In storefront/settings.py, point the default storage at the bucket. Keep the staticfiles storage from the deploy guide:

storefront/settings.py

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.s3.S3Storage",
        "OPTIONS": {
            "bucket_name": env("S3_BUCKET"),
            "endpoint_url": env("S3_ENDPOINT"),
            "access_key": env("S3_ACCESS_KEY_ID"),
            "secret_key": env("S3_SECRET_ACCESS_KEY"),
            "region_name": "auto",
            "signature_version": "s3v4",
            # Keep uploads with the same name instead of replacing the older file.
            "file_overwrite": False,
        },
    },
    "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"},
}

Every FileField and ImageField now saves to the bucket, and file.url returns a link that works for 1 hour (django-storages’ default querystring_expire is 3600 seconds). See presigned URLs. For a public bucket, return permanent URLs on the bucket’s public domain instead. Add the S3_PUBLIC_DOMAIN variable to the application, then add two options:

storefront/settings.py

            "custom_domain": env("S3_PUBLIC_DOMAIN"),
            "querystring_auth": False,

See public URLs. Commit and push the changes, requirements.txt included. If Auto-deploy is off, click Deploy now on the application’s Overview tab. The build log warns Django's collectstatic runs during the build, and the settings read environment variables without a default: with the variables Available during buildtime, the build passes.

Verify

When the deployment’s status is Deployed, click the application’s Web terminal tab, and in the shell that opens in the Web process, save a test file through Django’s storage:

python manage.py shell -c "from django.core.files.base import ContentFile; from django.core.files.storage import default_storage; name = default_storage.save('hello.txt', ContentFile(b'Hello from Sevalla')); print(default_storage.url(name))"

The command prints the file’s URL. Open it: the page reads Hello from Sevalla. In the sidebar, click Object storage, click the bucket, and the Objects tab lists hello.txt. To remove it, run default_storage.delete('hello.txt') the same way, or delete it on the Objects tab. See Manage objects. A script or an AI agent runs the same command with Run a command in a process (execProcessCommandV3), opens the URL it prints, and lists the bucket with List objects (listObjectStorageObjectsV3). APP_ID and WEB_ID come from Deploy with the API, and BUCKET_ID from Deploy with the API:

FILE_URL=$(curl -s -X POST "$API/applications/$APP_ID/processes/$WEB_ID/exec" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"command": ["python", "manage.py", "shell", "-v", "0", "-c", "from django.core.files.base import ContentFile; from django.core.files.storage import default_storage; name = default_storage.save(\"hello.txt\", ContentFile(b\"Hello from Sevalla\")); print(default_storage.url(name))"]}' \
  | jq -r .stdout)
curl -s "$FILE_URL"; echo
curl -s "$API/object-storage/$BUCKET_ID/objects" -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.data[].key'

Hello from Sevalla
hello.txt

Serve static files from the bucket

WhiteNoise with the Sevalla CDN serves static files well for most projects. To serve them from the bucket instead, make the bucket public and give media and static files their own folders with location:

storefront/settings.py

S3_OPTIONS = {
    "bucket_name": env("S3_BUCKET"),
    "endpoint_url": env("S3_ENDPOINT"),
    "access_key": env("S3_ACCESS_KEY_ID"),
    "secret_key": env("S3_SECRET_ACCESS_KEY"),
    "region_name": "auto",
    "signature_version": "s3v4",
    "custom_domain": env("S3_PUBLIC_DOMAIN"),
    "querystring_auth": False,
}

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.s3.S3Storage",
        "OPTIONS": {**S3_OPTIONS, "location": "media", "file_overwrite": False},
    },
    "staticfiles": {
        "BACKEND": "storages.backends.s3.S3Storage",
        "OPTIONS": {**S3_OPTIONS, "location": "static"},
    },
}

Then remove whitenoise.middleware.WhiteNoiseMiddleware from MIDDLEWARE. The collectstatic that Ingot runs during the build now uploads the static files to the bucket, so builds take longer, and every variable must stay Available during buildtime. With your own Dockerfile, the build has no credentials to upload with: change the Dockerfile’s collectstatic step to RUN python -m compileall -q ., and upload the files in a job instead. On the Processes tab, create a Job named Collect static with the Custom start command python manage.py collectstatic --noinput, keep the Start policy at Before deployment, and deploy. Each deployment’s build log then shows Collect static has been successful before the new version starts. Pages link to the files on the public domain, for example https://storefront-media-q8w2e.sevalla.storage/static/admin/css/base.css. Media files are public too, because public access applies to the whole bucket.

Deploy with the API

This sequence creates the bucket and adds its details to the application from Deploy with the API, and continues in its shell, with API and APP_ID set. Run it before you push the code changes from Install django-storages and Configure the storage, because the build needs the variables, and push them before the Deploy step. Each step names the CLI command and the Sevalla MCP server tool that do the same.

Create the bucket

Create object storage bucket (createObjectStorageV3) creates a private bucket. location is where most requests come from, here weur (Western Europe) for an application in Frankfurt. The response is the only one that contains the access key and the secret key, so keep it:

BUCKET=$(curl -s -X POST "$API/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)
echo "$BUCKET" | jq -r .bucket_name

It prints the bucket name, such as storefront-media-q8w2e. CLI: sevalla object-storage create --name storefront-media --location weur. MCP: sevalla_api_create with createObjectStorageV3 and the same body.

Add the environment variables

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

for pair in "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)"; do
  curl -s -X POST "$API/applications/$APP_ID/env-vars" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
    -d "$(jq -n --arg key "${pair%%=*}" --arg value "${pair#*=}" '{key: $key, value: $value, is_runtime: true, is_buildtime: true}')" \
    | jq -r .key
done

CLI: sevalla apps env-vars create "$APP_ID" --key S3_BUCKET --value <bucket name>, once per variable. MCP: set_environment_variables.

Deploy

Push the code changes, then Trigger deployment (triggerDeploymentV3). With Auto-deploy on, the push already started a deployment of the same commit; this one queues behind it:

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

CLI: sevalla apps deployments trigger "$APP_ID". MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) reports the status, which ends as success, failed, cancelled or skipped. The loop keeps polling through a failed request, for up to 30 minutes:

for i in $(seq 1 120); do
  STATUS=$(curl -s "$API/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"

CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Then run the checks in Verify. For a public bucket, Enable CDN domain (createObjectStorageDomainV3) turns on public access and returns the public domain in domain, for S3_PUBLIC_DOMAIN.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Store Django media in object storage

At a glance

Environment variables

Before you begin

Create a bucket

Add the bucket details to the application

Install django-storages

Configure the storage

Verify

Serve static files from the bucket

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create a bucket

​Add the bucket details to the application

​Install django-storages

​Configure the storage

​Verify

​Serve static files from the bucket

​Deploy with the API

At a glance

Environment variables

Before you begin

Create a bucket

Add the bucket details to the application

Install django-storages

Configure the storage

Verify

Serve static files from the bucket

Deploy with the API