Storage

Configure where Clipzy stores uploaded videos and processing results — local disk or Amazon S3.

Clipzy supports two storage backends: local for development and single-node deployments, and S3 for production and scalable deployments. Set the backend using the STORAGE_TYPE environment variable.

Local storage

Local storage writes files directly to disk on the machine running Clipzy. It requires no external services and is the simplest option for getting started.

STORAGE_TYPE=local
LOCAL_STORAGE_PATH=./storage

LOCAL_STORAGE_PATH can be an absolute or relative path. Clipzy creates the directory if it does not exist. The process must have read and write access to this path.

When using local storage, storage_url values in API responses are relative paths:

{
  "job_id": "job_abc123",
  "status": "completed",
  "result": {
    "storage_url": "/storage/results/job_abc123/output.json"
  }
}

Local storage is not suitable for multi-worker deployments. If you run more than one worker process, all workers must share the same filesystem (e.g. via a network mount). Otherwise, workers may be unable to read files written by other workers.

S3 storage

Set STORAGE_TYPE=s3 to store files in Amazon S3 or an S3-compatible service (e.g. MinIO, Cloudflare R2).

STORAGE_TYPE=s3

You must also configure your S3 credentials and bucket. Clipzy reads standard AWS environment variables:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_DEFAULT_REGION=us-east-1
S3_BUCKET_NAME=your-clipzy-bucket

When running on AWS infrastructure (EC2, ECS, Lambda), you can omit AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY and grant access via an IAM role attached to your instance or task instead.

When using S3 storage, storage_url values in API responses are pre-signed S3 URLs:

{
  "job_id": "job_abc123",
  "status": "completed",
  "result": {
    "storage_url": "https://your-clipzy-bucket.s3.amazonaws.com/results/job_abc123/output.json?X-Amz-Signature=..."
  }
}

Pre-signed URLs expire after a set duration. Download result files promptly after the job completes.

Choosing a backend

	Local	S3
Setup complexity	None	Requires AWS credentials and bucket
Multi-worker support	Only with shared filesystem	Yes
Scalability	Limited by disk	Effectively unlimited
Recommended for	Development, single-node	Production, multi-worker

Upload size limit

Regardless of storage backend, the MAX_FILE_SIZE_MB variable controls the maximum allowed upload size. Uploads exceeding this limit are rejected before any file is written to storage.

MAX_FILE_SIZE_MB=2000

If you handle long-form content, increase MAX_FILE_SIZE_MB and also update the client_max_body_size directive in your nginx or other reverse proxy configuration to match.