Media storage — local, S3 & Filebase
Operator guide
Media storage — local, S3 & Filebase
User media (photos, videos, avatars, covers) is stored on one of three disks.
The choice is made in the admin panel at Settings → Media Storage and/or in
.env via MEDIA_STORAGE_DISK.
| Mode | Disk | Where files live |
|---|---|---|
local |
public |
This server, storage/app/public |
managed_filebase |
filebase |
A Filebase S3 bucket (platform-managed or your own) |
admin_s3 |
s3 |
Your own S3-compatible bucket (AWS, DigitalOcean Spaces, MinIO…) |
How the choice is applied
MediaStorage::disk()maps the mode to the actual filesystem disk (app/Support/MediaStorage.php).- Credentials can live in two places:
.env(the traditional way) or the admin panel (Settings → Media Storage), where they're stored encrypted in the database and applied lazily — no shell access needed. - When you switch, new uploads go to the new location; existing files stay where they are (they are never auto-migrated).
Option A — local (default, zero config)
MEDIA_STORAGE_DISK=local
Files are stored in storage/app/public and served from /storage via the
storage:link. Fine for small communities; watch disk quota as you grow.
Option B — your own S3 (admin_s3)
Any S3-compatible provider works. In the admin panel (Settings → Media Storage) choose "My own S3 account" and fill in:
- Access key ID / Secret access key
- Bucket
- Region (e.g.
us-east-1) - Endpoint — leave blank for AWS; set for Spaces/MinIO/others
- Bucket URL — optional custom CDN/domain
Or in .env:
MEDIA_STORAGE_DISK=admin_s3
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket
Bucket permissions: objects must be publicly readable for media URLs to work. The app uses long random object keys, so public-read buckets are safe. Enable path-style endpoints for non-AWS providers.
Option C — Filebase (managed_filebase)
Filebase is an S3-compatible provider ideal for cheap, decentralised storage. Use the platform-managed bucket or your own Filebase account:
MEDIA_STORAGE_DISK=managed_filebase
FILEBASE_ACCESS_KEY=...
FILEBASE_SECRET_KEY=...
FILEBASE_REGION=us-east-1
FILEBASE_BUCKET=your-bucket
FILEBASE_URL=https://s3.filebase.com
FILEBASE_ENDPOINT=https://s3.filebase.com
Test the connection
In the admin panel (Settings → Media Storage) click Test connection after choosing a cloud mode. It writes and deletes a probe object on the target disk.
Migrating existing media (manual)
There is no built-in migration tool. To move an existing library:
# Example: copy local public storage into an S3 bucket using the aws CLI
aws s3 sync storage/app/public s3://your-bucket/ --exclude ".gitignore"
Then switch MEDIA_STORAGE_DISK. Old URLs pointing at /storage/... will stop
resolving for moved files — re-point them or keep a redirect.
Troubleshooting
| Symptom | Likely fix |
|---|---|
| Uploads fail silently when cloud selected | Credentials missing/empty in settings or .env — MediaStorage falls back to local |
| URLs 404 | Bucket not public-read, or path-style endpoint needed |
| "Nothing changed" after switching | Correct — existing files stay; only new uploads move. Use the Test connection button |
Related
Still stuck? Contact the node administrator.