Filesystem Storage (FileSystemStorage)¶

FileSystemStorage stores files on the local filesystem. It's built into amsdal_framework — no additional packages needed.

When to Use¶

Single-server deployments
Development and testing
When you have a mounted volume (NFS, EFS) shared across instances
When you need publicly accessible file URLs via a web server or CDN

Not recommended for multi-server deployments without shared storage, or when you need durability guarantees beyond the local disk.

Configuration¶

Constructor Parameters¶

Parameter	Type	Default	Description
`base_dir`	`str`	`MEDIA_ROOT` setting	Root directory where files are stored.
`base_url`	`str`	`MEDIA_URL` setting	URL prefix for generating public file URLs.

Using Settings (Recommended)¶

When you omit constructor parameters, FileSystemStorage uses the framework settings:

from amsdal.storages.file_system import FileSystemStorage

# Uses MEDIA_ROOT and MEDIA_URL from settings
storage = FileSystemStorage()

Configure via environment variables:

Setting	Env Variable	Default	Description
`MEDIA_ROOT`	`AMSDAL_MEDIA_ROOT`	`./media`	Root directory for stored files
`MEDIA_URL`	`AMSDAL_MEDIA_URL`	`/media/`	URL prefix for public file access

Explicit Configuration¶

from amsdal.storages.file_system import FileSystemStorage

storage = FileSystemStorage(
    base_dir='/var/media',
    base_url='https://cdn.example.com/media/',
)

Setting as Default¶

Via environment variable:

export AMSDAL_DEFAULT_FILE_STORAGE='amsdal.storages.file_system.FileSystemStorage'

Or via code:

from amsdal.storages import set_default_storage
from amsdal.storages.file_system import FileSystemStorage

set_default_storage(FileSystemStorage())

Per-Field Usage¶

from amsdal.storages.file_system import FileSystemStorage
from amsdal.models.core.file import File
from amsdal_models.classes.fields.file import FileField
from amsdal_models.classes.model import Model

class MyModel(Model):
    attachment: File = FileField(
        storage=FileSystemStorage('/var/media', 'https://cdn.example.com/media/'),
    )

How It Works¶

When a File is saved with FileSystemStorage:

On save — file bytes are written to {base_dir}/{filename} in 8 KB chunks. If a file with the same name already exists, a unique suffix is appended to avoid collisions.
On open — the file is opened from disk and returned as a standard file stream.
On delete — the file is removed from disk.
URL — returns {base_url}{filename} (e.g. https://cdn.example.com/media/report.pdf).

FileSystemStorage sets keeps_local_copy = False, so the framework may clear the in-memory data field after the file has been written to disk.

Async Support¶

Async operations (asave, aopen, adelete, aexists, aurl) use aiofiles for non-blocking file I/O. Make sure aiofiles is installed if you're running in async mode:

pip install aiofiles

Serving Files¶

FileSystemStorage writes files to disk but does not serve them over HTTP. You need to configure your web server or CDN to serve the MEDIA_ROOT directory at the MEDIA_URL prefix.

For example, with Nginx:

location /media/ {
    alias /var/media/;
}