File Stores

File Stores Overview

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 vs S3 Storage

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.

Configuring a File Store

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.

Structure and Permissions

A file store is more than a path. It has a structure inside it and its own permissions.

Where to find it

Architect Panel → Data:

• File Stores — the stores themselves, and View File Store on a row
• Large Uploads — in-progress and stalled upload sessions
• File Import Routines — watched sources and their mappings

Admin Panel → User Administration:

• User Groups — the groups a store is granted to

Each store has a folder tree

Entries inside a store name their parent, so folders nest. Each entry says whether it is a file or a folder and carries a version number, which is what allows a file to be replaced without losing what came before.

So a store is a small filing system rather than a flat bucket.

Physical and virtual

Store fields can allow physical entries, virtual ones, or both. A physical entry is a real file on disk or in object storage; a virtual one is a reference to something held elsewhere.

That distinction is what lets a store present files from more than one source as one structure.

Permissions are per store, per group

Each grant names a security group and what it may do. So one store can be readable by everybody and writable by a few, and another visible only to a single team.

Grant stores, not folders

Permissions attach to the store. If two sets of people need genuinely different access, that is usually two stores rather than one store with an arrangement of folders nobody can enforce.

Designing the store boundaries around who may see what is the decision that makes the permissions simple.

Design the tree before loading anything

A store that grows organically becomes a place people cannot find things in, and reorganising it breaks every reference to a file inside it.

A shallow, obvious structure — by year, by customer, by type — beats a deep one that reflects an organisational chart that will change.

Versioning is per entry

Replacing a file creates a new version rather than overwriting. Worth knowing both because it protects you and because it means a store grows faster than the files people think they have put in it.

Review the grants

File stores accumulate access. Somebody added for a project, a group repurposed, a store created for one team and now used by three. It is a short list per store and worth reading occasionally.

Use "View File Store" from the row

The store’s contents are reached as a row action rather than from a menu. That is easy to miss, and it is where you actually work with the files.

Worked example

An organisation runs three stores — public assets readable by everybody, customer documents restricted to the account team, and HR files restricted to two people. Each has a shallow tree by year. Splitting by audience rather than folder made the permissions a three-line answer.

Recommendations

• Separate stores by audience, not folders within one.
• Design a shallow tree before loading files.
• Remember versioning — stores grow faster than expected.
• Review grants per store periodically.