File Storage

The ALTCHA Forms application offers flexible file storage options for uploaded files. You can store files locally on your server or use a remote S3-compatible object storage service. This document explains how to configure both options.

Local Filesystem

By default, uploaded files are stored in the ./data folder. You can change this location by setting the STORAGE_FS_DIR environment variable.

S3 Storage

For production environments, we recommend using an S3-compatible object storage service. To enable S3 storage, configure the following environment variables with your S3 credentials and bucket details:

STORAGE_PROVIDER=s3
STORAGE_S3_ACCESS_KEY_ID=your_access_key_id
STORAGE_S3_SECRET_ACCESS_KEY=your_secret_access_key
STORAGE_S3_BUCKET=your_bucket_name

CORS Policy

When using S3 storage, end-users receive a pre-signed upload URL pointing to the S3 endpoint. To ensure uploads work correctly, configure the CORS Policy to allow requests from your application domain (BASE_URL). Make sure to whitelist the GET and PUT methods.

Object Lifecycle Rules

To manage temporary files, configure Object Lifecycle rules to automatically delete objects in the /tmp folder after a certain period. This folder serves as temporary storage, and a 1-day retention period is usually sufficient to manage temporary files effectively.

Usage with CloudFlare’s R2

CloudFlare’s R2 service is also supported. To configure R2, set the following additional environment variables:

STORAGE_S3_ENDPOINT=https://account_id.eu.r2.cloudflarestorage.com/bucket_name
STORAGE_S3_REGION=auto

You can find the ENDPOINT URL in your CloudFlare account under R2 -> Select bucket -> Settings and look for S3 API.

File Organization

Files are initially uploaded to the /tmp subfolder. After a successful upload and linking with its associated entity (such as a form response), the file is moved to the /persistent folder.

Stored files are organized into subfolders based on account ID and date, following this structure:

/(tmp|persistent)/[account_id]/[date]/[file_id]

For example: /persistent/acc_1j7la75euGFW8tmHtJgPL/2024-07-01/file_1j90i3seu7H7bMPwRnbhM.