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=s3STORAGE_S3_ACCESS_KEY_ID=your_access_key_idSTORAGE_S3_SECRET_ACCESS_KEY=your_secret_access_keySTORAGE_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_nameSTORAGE_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
.