Skip to main content
ClassQuiz supports two storage backends for uploaded media files: local filesystem storage and S3-compatible object storage. This guide covers how to configure each option.

​
Storage Backend Selection

​
STORAGE_BACKEND
string
required
The storage backend to use for uploaded files.Options:
  • local - Store files on the local filesystem
  • s3 - Store files in S3-compatible object storage
Example: local or s3

​
Local Storage Configuration

When using STORAGE_BACKEND=local, files are stored directly on the server’s filesystem.
​
STORAGE_PATH
string
required
Absolute path to the directory where uploaded files will be stored.Docker default: /app/dataExample: /var/lib/classquiz/uploads

​
Local Storage Setup

1

Set storage backend

Configure the storage backend to use local filesystem:
STORAGE_BACKEND=local
STORAGE_PATH=/app/data
2

Configure volume mount (Docker)

Ensure the storage path is mounted as a volume in your docker-compose.yml:
volumes:
  - ./uploads:/app/data
This maps the local ./uploads directory to /app/data in the container.
3

Set permissions

Ensure the application has write permissions to the storage directory:
mkdir -p ./uploads
chmod 755 ./uploads
Local storage is not recommended for production deployments with multiple instances, as files won’t be shared across containers. Use S3 for scalable deployments.

​
S3-Compatible Storage Configuration

When using STORAGE_BACKEND=s3, files are stored in S3-compatible object storage (AWS S3, MinIO, DigitalOcean Spaces, etc.).
​
S3_ACCESS_KEY
string
required
Access key ID for S3 authentication.Example: AKIAIOSFODNN7EXAMPLE
​
S3_SECRET_KEY
string
required
Secret access key for S3 authentication.Example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
​
S3_BUCKET_NAME
string
default:"classquiz"
Name of the S3 bucket where files will be stored.The bucket will be automatically created if it doesn’t exist.
​
S3_BASE_URL
string
required
Base URL of your S3-compatible storage service.Examples:
  • AWS S3: https://s3.amazonaws.com or https://s3.us-west-2.amazonaws.com
  • MinIO: https://minio.example.com
  • DigitalOcean Spaces: https://nyc3.digitaloceanspaces.com

​
S3 Storage Setup

1

Create S3 bucket

Create a bucket in your S3-compatible storage provider. ClassQuiz can auto-create the bucket if your credentials have sufficient permissions.
2

Configure credentials

Set up your S3 credentials and endpoint:
STORAGE_BACKEND=s3
S3_ACCESS_KEY=your-access-key
S3_SECRET_KEY=your-secret-key
S3_BUCKET_NAME=classquiz
S3_BASE_URL=https://s3.amazonaws.com
3

Set bucket permissions

Ensure your IAM user/role has the following permissions:
  • s3:PutObject - Upload files
  • s3:GetObject - Download files
  • s3:DeleteObject - Delete files
  • s3:ListBucket - List bucket contents
  • s3:CreateBucket - Create bucket (optional, if auto-create is needed)

​
Configuration Examples

STORAGE_BACKEND=local
STORAGE_PATH=/app/data

# In docker-compose.yml:
volumes:
  - ./uploads:/app/data

​
Storage Limits

By default, each user has a storage quota of 1 GB (1,074,000,000 bytes). You can adjust this limit: 
FREE_STORAGE_LIMIT=1074000000  # 1 GB in bytes
To calculate storage limits:
  • 100 MB = 104857600
  • 500 MB = 524288000
  • 1 GB = 1074000000
  • 5 GB = 5368709120

​
Supported File Types

ClassQuiz supports the following MIME types for uploads:
  • image/png
  • image/jpeg
  • image/gif
  • image/webp
  • video/mp4

​
Migration Between Storage Backends

ClassQuiz does not provide built-in tools for migrating between storage backends. If you need to switch from local to S3 (or vice versa), you’ll need to manually copy files and update references.

​
Migration Steps

1

Export file list

Create a list of all files currently stored in your old storage backend.
2

Copy files

Use aws s3 sync or similar tools to copy files to the new storage location.
3

Update configuration

Change your STORAGE_BACKEND and related environment variables.
4

Test uploads

Verify that new uploads work correctly with the new storage backend.

​
Troubleshooting

Check that:
  • Your S3 credentials are correct
  • The bucket exists or your credentials allow bucket creation
  • Your IAM permissions include s3:PutObject
  • The S3_BASE_URL is correct for your region
Ensure the application has write permissions:
sudo chown -R 1000:1000 ./uploads
chmod -R 755 ./uploads
For S3 storage, ensure your bucket policy allows public read access for uploaded files, or that pre-signed URLs are being generated correctly.

​
Next Steps

Environment Variables

View all configuration options

External Services

Configure database and cache services

Build docs developers (and LLMs) love

Get started for freeTalk to us