File Stores

A File Store is a named location where the platform stores uploaded files. Every File Upload field on every datastore picks which File Store to use. You can have multiple file stores — perhaps one per customer tenant, one for public files, one for private documents, one for archive — and each can have its own storage backend, permissions, and lifecycle.

Storage modes

The platform supports two storage backends:

Local

Files live on the web server's filesystem. The platform writes them under a configured path (typically inside the web root for public files or outside for private files).

Simpler to set up — no AWS account needed, no per-GB costs, no networking concerns. Suitable for single-server installs with modest file storage needs.

Doesn't scale across multiple web servers — each server has its own filesystem, so a file uploaded to server A won't be visible to server B. Backup is your responsibility (no automatic replication).

S3

Files live in AWS S3 (or any S3-compatible storage service like MinIO, DigitalOcean Spaces, or Cloudflare R2). The platform reads and writes via the AWS SDK.

Scales infinitely. Built-in replication, lifecycle policies (auto-archive to cheaper storage tiers), versioning, encryption. Works with multi-server deployments out of the box — every server reads from the same S3 bucket.

Requires an AWS account and pays per-GB storage + per-request costs. Slight latency overhead per file access (network call vs filesystem read).

Where to manage them

Architect Panel → File Stores. The list shows every configured File Store with its name, storage mode, and statistics (file count, total size).

Three real-world File Store configurations

Example 1: Single S3 bucket for everything

One File Store backed by one S3 bucket. All uploaded files across all datastores land here. Simple to manage; suitable for small-to-medium installs where file segregation isn't critical.

Example 2: Per-tenant File Stores

For multi-tenant installs with strict data-isolation needs, each tenant gets their own File Store backed by their own S3 bucket (or a per-tenant prefix in a shared bucket). Tenant files never cross over even at the storage layer.

Example 3: Public/private split

Two File Stores. "Public Assets" backed by an S3 bucket with public-read ACLs — for product images, marketing assets. "Private Documents" backed by a private bucket with restricted access — for contracts, IDs, sensitive uploads. File Upload fields on different datastores pick whichever store is appropriate.

Local and S3 are the two storage modes for File Stores. Each has trade-offs around cost, scalability, complexity, and feature richness. The right choice depends on your hosting model, expected file volumes, and security requirements.

Local storage

Files written to the web server's filesystem.

Pros

• Simpler — no AWS account needed, no cloud-storage SDK calls.
• Cheaper for small volumes — within your web server's existing disk allocation.
• No network latency — reads and writes are local filesystem operations.
• Easier to inspect during development — files are just there, on disk, can be examined with normal Unix tools.

Cons

• Doesn't scale across multiple web servers — each server has its own filesystem. A file on server A isn't visible to server B.
• Backup is your responsibility — no automatic replication. Filesystem snapshots and offsite backups are on you.
• Local disk is finite — limited by the server's storage capacity.
• Single-server failure means file loss if you haven't backed up.

S3 storage

Files written to AWS S3 or an S3-compatible service.

Pros

• Scales infinitely — no practical capacity limit.
• Built-in replication and durability — S3 stores multiple copies across availability zones automatically. AWS quotes 99.999999999% durability.
• Multi-server-friendly — every web server reads from the same bucket. Load balancing just works.
• Lifecycle policies — automatic transition to cheaper storage tiers (Glacier, Glacier Deep Archive) for old files.
• Native encryption — server-side encryption with AWS-managed or customer-managed keys.
• CDN integration — front the bucket with CloudFront for fast global delivery.

Cons

• Requires AWS account (or compatible service).
• Per-GB cost — typically $0.023/GB/month for standard tier. Plus per-request costs ($0.0004 per 1000 GET requests).
• Slight latency overhead — typically 20-100ms per S3 operation vs sub-millisecond local disk.

Recommendation

For production deployments and especially multi-server setups, use S3. The scalability and durability benefits massively outweigh the modest per-GB cost. For dev/staging or single-server installs that won't grow, local is fine and saves some operational overhead.

Migrating between modes

If you start with local and outgrow it, migrating to S3 is a one-time job:

1. Set up the S3 bucket with the right policies.
2. Sync the existing local files into the bucket (e.g. with aws s3 sync).
3. Update the File Store configuration to switch from Local to S3.
4. Verify file URLs still resolve correctly.
5. After confirmation, optionally remove the local copies to free disk space.

Plan downtime for this — between the time you switch modes and the time files are accessible at their new locations, file links can break.

From the Architect Panel → File Stores, click New. The configuration depends on the storage mode you pick.

Common fields

• Name — internal name shown in dropdowns where File Stores are referenced.
• Description — optional. Useful for documenting what this File Store is intended for.
• Storage Mode — Local or S3.
• Public / Private — whether files are directly URL-accessible:
  • Public: files have a guessable URL and can be accessed without authentication.
  • Private: files are only accessible via fetchfile.php which enforces permissions.
• Allowed File Types — restrict uploads to specific MIME types or extensions.
• Max File Size — reject uploads above this size.

Local-mode settings

When Storage Mode = Local:

• Path — directory where files are stored. Relative to the platform's root for public stores; outside the web root for private stores.
• URL Prefix — the URL path that the platform serves files from (for public stores).

S3-mode settings

When Storage Mode = S3:

• Bucket Name — the S3 bucket.
• Region — AWS region the bucket lives in.
• Access Key / Secret — AWS credentials. Or, if running on EC2, leave blank to use the instance's IAM role.
• Path prefix — optional sub-path inside the bucket (useful for sharing one bucket between multiple File Stores).
• Optional CloudFront distribution for CDN delivery — set the CloudFront URL here and the platform serves files via the CDN.

Testing

Upload a test file via a File Upload field pointing at the new store. Verify:

1. The upload completes without errors.
2. The file appears in the configured location (local path or S3 bucket).
3. The file is retrievable via the platform's UI (downloads or displays correctly).
4. For public stores: the file URL works in an incognito browser without authentication.
5. For private stores: the file URL via fetchfile.php works for authorised users but returns 403 for unauthorised.

Three real-world configurations

Example 1: Public marketing assets

Name: "Marketing Assets". Storage Mode: S3. Public: yes. Bucket: acme-marketing-assets. CloudFront distribution configured for fast global delivery. Used for product images, hero photos, logos referenced from public pages.

Example 2: Private customer documents

Name: "Customer Documents". Storage Mode: S3. Public: no. Bucket: acme-customer-private with bucket policy blocking public access. Files only served via fetchfile.php with permission checks. Used for contracts, ID uploads, signed documents.

Example 3: Local development store

Name: "Dev Uploads". Storage Mode: Local. Public: no. Path: /var/data/dev-uploads (outside the web root). Used during development for everything; production uses S3 instead.