Store Laravel files in object storage

Laravel saves files to its local disk, in storage/app, by default, and Sevalla resets an application’s filesystem on every deployment. With Laravel’s s3 disk, Laravel 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

What this guide adds to the application from Deploy a Laravel application:


Services	A Sevalla object storage bucket, private by default, reached over its S3-compatible API

Environment variables

Variable	Required	Available during	Secret	Value
`FILESYSTEM_DISK`	Yes	Runtime	No	`s3`
`AWS_BUCKET`	Yes	Runtime	No	The bucket’s Bucket name (`bucket_name` in the API), for example `storefront-media-q8w2e`
`AWS_ENDPOINT`	Yes	Runtime	No	The bucket’s Endpoint (`endpoint`), `https://<account-id>.r2.cloudflarestorage.com`
`AWS_ACCESS_KEY_ID`	Yes	Runtime	Yes	The bucket’s Access key (`access_key`)
`AWS_SECRET_ACCESS_KEY`	Yes	Runtime	Yes	The bucket’s Secret key (`secret_key`)
`AWS_DEFAULT_REGION`	Yes	Runtime	No	`auto`
`AWS_URL`	Public buckets only	Runtime	No	`https://` and the bucket’s Public domain (`domain`)

The application’s other variables are in Deploy a Laravel application.

Before you begin

A Laravel application deployed on Sevalla, as in Deploy Laravel.

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.

Install the S3 driver

Laravel’s s3 disk needs Flysystem’s S3 adapter, which installs the AWS SDK for PHP:

composer require league/flysystem-aws-s3-v3 "^3.0" --with-all-dependencies

Add the bucket details to the application

Laravel’s config/filesystems.php reads the s3 disk’s settings from these variables, so the configuration files don’t change. The values come from the bucket’s Settings tab; see Connect with the S3 API for each one.

Variable	Value
`FILESYSTEM_DISK`	`s3`, which makes the bucket Laravel’s default disk
`AWS_BUCKET`	Bucket name under Details, for example `storefront-media-q8w2e`. It’s not the display name.
`AWS_ENDPOINT`	Endpoint under Details, in the form `https://<account-id>.r2.cloudflarestorage.com`
`AWS_ACCESS_KEY_ID`	Access key under Access keys
`AWS_SECRET_ACCESS_KEY`	Secret key under Access keys
`AWS_DEFAULT_REGION`	`auto`
`AWS_URL`	Public buckets only: `https://` and the Public domain under Public access, for example `https://storefront-media-q8w2e.sevalla.storage`

Leave AWS_USE_PATH_STYLE_ENDPOINT unset: the bucket accepts requests with the bucket name in the host name, as Laravel sends them by default.

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 and click Add environment variables. They apply with the next deployment.

Store uploads

Add a route that saves an uploaded photo in the bucket and returns a link to it:

routes/web.php

<?php

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Storage;

Route::get('/', function () {
    return view('welcome');
});

Route::post('/photos', function (Request $request) {
    $request->validate(['photo' => ['required', 'image', 'max:10240']]);

    $path = $request->file('photo')->store('photos');

    return [
        'path' => $path,
        'url' => Storage::temporaryUrl($path, now()->addHour()),
    ];
});

store('photos') saves the file on the default disk, the bucket, under photos/ with a random name, and returns its path, for example photos/lMI1BYDbMqPcsYKXrHX2n5qT5ZGQBOXfrOd74drU.png. Save the path with your model.
max:10240 limits uploads to 10 MB. Ingot’s PHP accepts uploads up to 64 MB.
Send the file from a form with enctype="multipart/form-data", a file field named photo and @csrf, as every POST route in routes/web.php needs a CSRF token.

Commit and push the changes, composer.json and composer.lock included: Ingot installs the S3 adapter on the next build. If Auto-deploy is off, click Deploy now on the application’s Overview tab.

Link to the files

For a private bucket, Storage::temporaryUrl($path, now()->addHour()) returns a presigned URL that works for 1 hour, up to 7 days. Create it when you show the page, not when you save the file. For a public bucket with AWS_URL set, Storage::url($path) returns a permanent URL on the bucket’s public domain, for example https://storefront-media-q8w2e.sevalla.storage/photos/lMI1BYDbMqPcsYKXrHX2n5qT5ZGQBOXfrOd74drU.png. Public access applies to the whole bucket: the bucket doesn’t keep per-file visibility, so Storage::getVisibility() fails with GetObjectAcl not implemented. Keep private files in a second, private bucket, with a second disk in config/filesystems.php. See Public URLs.

Update the Dockerfile

If the application builds from the Dockerfile in the deploy guide, raise PHP’s upload limits, which are 2 MB per file in PHP’s production php.ini, to Ingot’s 64 MB. Add a line to the php.ini settings of the first RUN instruction, before the > "$PHP_INI_DIR/conf.d/production.ini" line:

Dockerfile

        'upload_max_filesize = 64M' 'post_max_size = 64M' \

The AWS SDK needs no other extension or package: it uses PHP’s built-in curl and the root certificates the image already installs.

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 Laravel’s storage:

php artisan tinker --execute "Storage::put('hello.txt', 'Hello from Sevalla'); echo Storage::temporaryUrl('hello.txt', now()->addHour());"

The command prints the file’s temporary URL. Open it: the page reads Hello from Sevalla. For a public bucket, Storage::url('hello.txt') prints https://storefront-media-q8w2e.sevalla.storage/hello.txt, which shows the same text. In the sidebar, click Object storage, click the bucket, and the Objects tab lists hello.txt. To remove it, run Storage::delete('hello.txt') the same way, or delete it on the Objects tab. See Manage objects. If Storage::put() returns false, Laravel couldn’t write to the bucket: its s3 disk doesn’t throw errors by default. Check the variables, and set 'throw' => true for the s3 disk in config/filesystems.php to see the error.

Check from a terminal

These checks need no dashboard. API, H, APP_ID, WEB_ID and BUCKET_ID are set as in Deploy with the API.

Save a file and get its temporary URL, with Run a command in a process (execProcessCommandV3) in the web process, the API’s counterpart of the web terminal. The command runs without a shell, and the key needs write access to the application. Then open the URL:

URL=$(curl -s -X POST "$API/applications/$APP_ID/processes/$WEB_ID/exec" -H "$H" -H "Content-Type: application/json" \
  -d '{"command": ["php", "artisan", "tinker", "--execute", "Storage::put(\"hello.txt\", \"Hello from Sevalla\"); echo Storage::temporaryUrl(\"hello.txt\", now()->addHour());"], "timeout": 30}' \
  | jq -r .stdout)
curl -s "$URL"

Hello from Sevalla

The file in the bucket, from List objects (listObjectStorageObjectsV3):

curl -s "$API/object-storage/$BUCKET_ID/objects" -H "$H" | jq -c '.data[] | {key, size}'

{"key":"hello.txt","size":18}

To remove it, run Storage::delete('hello.txt') the same way, or call Delete objects. CLI: sevalla object-storage objects list --bucket-id $BUCKET_ID. MCP: sevalla_api_update with execProcessCommandV3, and sevalla_api_read with listObjectStorageObjectsV3.

Deploy with the API

The same steps as Create a bucket and Add the bucket details to the application, as calls to the Sevalla API. APP_ID and WEB_ID are the application and its web process from Deploy with the API in the deploy guide, with API and H set as there. The API key also needs the capabilities to create and read object storage. Push the S3 driver and the route first: the deployment builds the branch as it is.

Create the bucket

Create object storage bucket (createObjectStorageV3) returns the bucket’s name, endpoint and keys. location is the region hint closest to the application, here weur (Western Europe) for Frankfurt; send "public_access": true for a public bucket:

BUCKET=$(curl -s -X POST "$API/object-storage" -H "$H" -H "Content-Type: application/json" \
  -d '{"display_name": "storefront-media", "location": "weur"}')
BUCKET_ID=$(echo "$BUCKET" | jq -r .id)
echo "$BUCKET" | jq -c '{bucket_name, endpoint, domain}'

The response holds the secret key, so the command prints only the other fields. 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, from the bucket’s details, for runtime only:

for pair in "FILESYSTEM_DISK=s3" "AWS_DEFAULT_REGION=auto" \
  "AWS_BUCKET=$(echo "$BUCKET" | jq -r .bucket_name)" "AWS_ENDPOINT=$(echo "$BUCKET" | jq -r .endpoint)" \
  "AWS_ACCESS_KEY_ID=$(echo "$BUCKET" | jq -r .access_key)" "AWS_SECRET_ACCESS_KEY=$(echo "$BUCKET" | jq -r .secret_key)"; do
  curl -s -X POST "$API/applications/$APP_ID/env-vars" -H "$H" -H "Content-Type: application/json" \
    -d "$(jq -n --arg key "${pair%%=*}" --arg value "${pair#*=}" '{key: $key, value: $value, is_runtime: true, is_buildtime: false}')" \
    | jq -r .key
done

For a public bucket, add AWS_URL with https:// and the bucket’s domain too. CLI: sevalla apps env-vars create $APP_ID --key FILESYSTEM_DISK --value s3, once per variable, for build and runtime. MCP: set_environment_variables with runtime: true and buildtime: false.

Deploy

Trigger deployment (triggerDeploymentV3):

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

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

Wait for the deployment

Poll Get deployment (getDeploymentV3) until the status is final: success, failed, cancelled or skipped. The loop keeps polling through a failed request and stops after 30 minutes:

for i in $(seq 1 120); do
  STATUS=$(curl -s "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID" -H "$H" | 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 Check from a terminal.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java and Kotlin

.NET

Elixir

Static site generators

Store Laravel files in object storage

At a glance

Environment variables

Before you begin

Create a bucket

Install the S3 driver

Add the bucket details to the application

Store uploads

Link to the files

Update the Dockerfile

Verify

Check from a terminal

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create a bucket

​Install the S3 driver

​Add the bucket details to the application

​Store uploads

​Link to the files

​Update the Dockerfile

​Verify

​Check from a terminal

​Deploy with the API

At a glance

Environment variables

Before you begin

Create a bucket

Install the S3 driver

Add the bucket details to the application

Store uploads

Link to the files

Update the Dockerfile

Verify

Check from a terminal

Deploy with the API