How to Manage Media and Storage in a Headless CMS

Organize Your Media: A Complete Guide to Asset Management and Storage in ElmapiCMS

Media management is a crucial part of any content management system. Whether you're uploading images for blog posts, product photos for an e-commerce site, or documents for a knowledge base, ElmapiCMS provides a powerful Asset Library that makes organizing and using media files simple and efficient.

In this guide, we'll walk through everything you need to know about managing media and storage in ElmapiCMS, from basic uploads to advanced cloud storage configuration.

Table of Contents

• What is the Asset Library?
• Step 1: Accessing the Asset Library
• Step 2: Uploading Assets
• Step 3: Organizing and Managing Assets
• Step 4: Using Assets in Content
• Understanding Storage Options
• Step 5: Configuring Local Storage
• Step 6: Configuring AWS S3 Storage
• Step 7: Using S3-Compatible Services
• Using Assets via API
• Best Practices
• Troubleshooting
• Next Steps
• Conclusion

What is the Asset Library?

The Asset Library is the central place in ElmapiCMS where you upload, organize, and manage all your media files. It's a unified storage system for images, videos, audio files, documents, and any other file types your project needs.

Key features:

• Centralized storage - All media files in one place
• Reusable assets - Use the same asset across multiple content entries
• Automatic metadata - File size, type, and dimensions extracted automatically
• Thumbnail generation - Automatic thumbnails for images
• Search and filter - Quickly find assets by name, type, or date
• Bulk operations - Select and manage multiple assets at once

Step 1: Accessing the Asset Library

1. Navigate to Your Project

   • Log in to your ElmapiCMS admin panel
   • Select the project where you want to manage assets

2. Open the Asset Library

   • Click on Asset Library in the left sidebar
   • You'll see a grid or table view of all uploaded assets

3. Understanding the Interface

   • Toolbar: Upload button, delete actions
   • Filters bar: Search box, type filter, date filter, sort options
   • Grid/Table view: Toggle between grid and list views
   • Asset cards: Each asset shows a thumbnail, filename, size, and type

Step 2: Uploading Assets

1. Open the Asset Library

   • Navigate to the Asset Library page

2. Click Upload Button

   • Click the Upload button in the toolbar
   • A file picker dialog opens

3. Select Files

   • Choose one or multiple files from your computer
   • Click Upload to start the upload

4. Upload Progress

   • Watch the upload progress
   • Assets are available immediately after upload

File Size Limits

File uploads are limited by:

• PHP settings: upload_max_filesize and post_max_size
• ElmapiCMS setting: MAX_FILE_SIZE in your .env file

The UI displays the exact file size limit. To increase limits, update your PHP configuration and .env file.

Step 3: Organizing and Managing Assets

Searching Assets

Search by name:

• Type in the search box to filter by filename
• Search matches filename, original filename, and MIME type
• Results update in real-time

Filter by type:

• Use the Type dropdown to filter by:
  • Image - All image files
  • Video - All video files
  • Audio - All audio files
  • Document - PDFs, Word docs, etc.

Filter by date:

• Use date filters: Today, Week, Month, Quarter
• Quickly find recently uploaded assets

Sorting Assets

Sort your assets by:

• Newest - Most recently uploaded first
• Oldest - Oldest files first
• Name - Alphabetical by filename
• Size - Largest or smallest files first

Viewing Asset Details

1. Click an Asset

   • Click any asset card to open the details modal

2. View Information

   • Preview: See the file (images show preview, videos can play)
   • Metadata: File size, dimensions, MIME type, upload date
   • URLs: Copy direct URL or thumbnail URL
   • Alt text: Edit alt text for images (accessibility)
   • Title: Edit display title

3. Actions Available

   • Edit: Modify alt text and title
   • View Details: See full metadata
   • Download: Download the original file
   • Delete: Remove the asset

Bulk Operations

Select Multiple Assets:

• Click checkboxes in the top-left corner of asset cards
• Select all assets on the current page

Bulk Delete:

• Select multiple assets
• Click Delete in the toolbar
• Confirm deletion
• Assets are permanently deleted

Deleting Assets

Delete:

• Click the three-dot menu (⋯) on an asset
• Select Delete
• Asset is permanently deleted

Step 4: Using Assets in Content

Assets in the Asset Library can be used in any Media field in your collections.

Adding Assets to Content

1. Create or Edit Content

   • Open a content entry form
   • Find a Media field

2. Select from Asset Library

   • Click the media field
   • The Asset Library modal opens
   • Browse or search for the asset you want
   • Click to select it

3. Multiple Assets

   • If the field allows multiple files, select multiple assets
   • Each selected asset appears in the field

4. Save Content

   • The asset is now linked to your content entry
   • The asset URL is stored in the entry's data

Media Field Options

Media fields can be configured as:

• Single file - One asset per entry
• Multiple files - Multiple assets per entry

Understanding Storage Options

ElmapiCMS supports two storage options for your assets:

Local Storage (Default)

How it works:

• Files are stored on your server's filesystem
• Assets are saved in storage/app/public/
• URLs point to your ElmapiCMS domain

Pros:

• Simple setup - no configuration needed
• No additional costs
• Fast access on the same server

Cons:

• Limited by server storage capacity
• Requires server backups
• May slow down if serving many large files
• Not ideal for high-traffic sites

Best for:

• Development and testing
• Small to medium projects
• Low-traffic websites
• When you want everything on one server

Cloud Storage (AWS S3 or S3-Compatible)

How it works:

• Files are stored in cloud storage (AWS S3, DigitalOcean Spaces, etc.)
• Assets are uploaded directly to your cloud bucket
• URLs point to your cloud storage or CDN

Pros:

• Scalable - no storage limits
• Fast delivery via CDN
• Automatic backups
• Reduces server load
• Professional solution for production

Cons:

• Requires cloud storage account
• Additional costs (usually minimal)
• Requires configuration

Best for:

• Production websites
• High-traffic applications
• Large media libraries
• When you need CDN delivery
• Multi-server deployments

Step 5: Configuring Local Storage

Local storage is the default option and requires no configuration. However, you can adjust file size limits.

Setting File Size Limits

In your .env file:

MAX_FILE_SIZE=5M

Note: This limit must be smaller than your PHP settings:

• upload_max_filesize in php.ini
• post_max_size in php.ini

Verifying Local Storage

1. Check Project Settings

   • Go to Settings → Project
   • Under Default Storage, it should show Local

2. Upload a Test File

   • Upload an asset to verify it works
   • Check that the file appears in the Asset Library

Step 6: Configuring AWS S3 Storage

Setting up AWS S3 for asset storage provides scalable, reliable cloud storage for your media files.

Prerequisites

Before you begin, you'll need:

• An AWS account
• An S3 bucket created in your desired region
• An IAM user with programmatic access credentials

Step 1: Create an S3 Bucket

1. Log in to AWS Console

   • Navigate to S3 service
   • Click Create bucket

2. Configure Bucket

   • Choose a unique bucket name
   • Select a region (e.g., us-east-1)
   • Configure public access settings based on your needs

3. Create Bucket

   • Click Create bucket

Step 2: Create IAM User

1. Navigate to IAM

   • Go to IAM service in AWS Console
   • Click Users → Create user

2. Set Permissions

   • Attach a policy with these permissions:
     • s3:PutObject
     • s3:PutObjectAcl
     • s3:GetObject
     • s3:DeleteObject
     • s3:ListBucket

3. Create Access Keys

   • After creating the user, go to Security credentials
   • Click Create access key
   • Choose Application running outside AWS
   • Save the Access Key ID and Secret Access Key

Step 3: Configure Environment Variables

Add these variables to your .env file:

AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket-name
AWS_URL=https://your-bucket-name.s3.us-east-1.amazonaws.com

Variable descriptions:

Step 4: Enable S3 Storage for Your Project

1. Open Project Settings

   • Navigate to Settings → Project

2. Select Storage

   • Under Default Storage, select AWS S3
   • Click Save

3. Test Upload

   • Upload a test asset
   • Verify it appears in your S3 bucket
   • Check that the URL points to S3

Using CloudFront CDN (Optional)

For better performance, you can use AWS CloudFront:

1. Create CloudFront Distribution

   • Point it to your S3 bucket
   • Get the CloudFront URL

2. Update AWS_URL

   • Set AWS_URL to your CloudFront URL
   • Example: https://d1234567890.cloudfront.net

Step 7: Using S3-Compatible Services

ElmapiCMS's S3 driver works with any S3-compatible storage service. This includes DigitalOcean Spaces, Backblaze B2, Wasabi, and self-hosted MinIO.

General Configuration

The setup is similar to AWS S3, with one addition: you must specify the service's API endpoint.

Additional environment variables:

AWS_ENDPOINT=https://your-service-endpoint.com
AWS_USE_PATH_STYLE_ENDPOINT=false  # Set to true for MinIO

DigitalOcean Spaces

1. Create a Space

   • In DigitalOcean, create a Space in your desired region

2. Generate Access Keys

   • Go to API → Spaces Keys
   • Create an access key and secret key

3. Configure Environment Variables

AWS_ACCESS_KEY_ID=YOUR_DO_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_DO_SECRET_KEY
AWS_DEFAULT_REGION=nyc3
AWS_BUCKET=your-space-name
AWS_URL=https://your-space-name.nyc3.cdn.digitaloceanspaces.com
AWS_ENDPOINT=https://nyc3.digitaloceanspaces.com

4. Enable S3 Storage
   • In Project Settings, select AWS S3 as Default Storage

Backblaze B2

1. Create a Bucket

   • Create a bucket in your Backblaze B2 account

2. Create Application Key

   • Create an Application Key with access to your bucket
   • Note the keyID and applicationKey

3. Configure Environment Variables

AWS_ACCESS_KEY_ID=YOUR_B2_KEY_ID
AWS_SECRET_ACCESS_KEY=YOUR_B2_APPLICATION_KEY
AWS_DEFAULT_REGION=us-west-004
AWS_BUCKET=your-b2-bucket-name
AWS_URL=https://your-b2-bucket-name.s3.us-west-004.backblazeb2.com
AWS_ENDPOINT=https://s3.us-west-004.backblazeb2.com

MinIO (Self-Hosted)

1. Set Up MinIO Server

   • Install and run MinIO on your server
   • Create a bucket and access keys

2. Configure Environment Variables

AWS_ACCESS_KEY_ID=YOUR_MINIO_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_MINIO_SECRET_KEY
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-minio-bucket-name
AWS_URL=http://your-minio-domain:9000/your-minio-bucket-name
AWS_ENDPOINT=http://your-minio-domain:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

Note: For MinIO, you must set AWS_USE_PATH_STYLE_ENDPOINT=true.

Using Assets via API

You can manage assets programmatically through the ElmapiCMS API.

Listing Assets

import { createClient } from '@elmapicms/js-sdk';

const client = createClient(
  'https://your-domain.com/api',
  'YOUR_API_TOKEN',
  'YOUR_PROJECT_UUID'
);

// List all assets
const assets = await client.getAssets();

// List with filtering
const images = await client.getAssets({
  paginate: 20,
  type: 'image',
  search: 'hero'
});

Getting a Single Asset

// Get asset by UUID or ID
const asset = await client.getAsset('asset-uuid-here');

// Get asset by filename
const asset = await client.getAssetByFilename('hero-image.jpg');

Uploading Assets

// Upload a file
const fileInput = document.querySelector('input[type="file"]');
const uploadedAsset = await client.uploadAsset(fileInput.files[0]);

// Upload with metadata
const uploadedAsset = await client.uploadAsset(fileInput.files[0], {
  alt: 'Hero image for homepage',
  category: 'marketing'
});

Deleting Assets

// Soft delete (can be restored)
await client.deleteAsset('asset-uuid-here');

// Permanent delete (cannot be undone)
await client.deleteAsset('asset-uuid-here', true);

Asset Response Structure

{
  "uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "filename": "hero-image.jpg",
  "original_filename": "My Hero Image.jpg",
  "mime_type": "image/jpeg",
  "size": 1258291,
  "url": "https://your-domain.com/storage/hero-image.jpg",
  "thumbnail_url": "https://your-domain.com/storage/thumbnails/hero-image.jpg",
  "metadata": {
    "width": 1920,
    "height": 1080
  }
}

Best Practices

1. Optimize Images Before Upload

Why: Reduces storage costs and improves load times.

How:

• Compress images using tools like TinyPNG or ImageOptim
• Use WebP format when possible
• Resize images to appropriate dimensions
• Remove EXIF data if not needed

2. Use Meaningful Filenames

Why: Makes assets easier to find and manage.

How:

• Use descriptive names: hero-image-homepage.jpg instead of IMG_1234.jpg
• Include context: product-photo-red-shirt-front.jpg
• Use hyphens instead of spaces

3. Add Alt Text for Images

Why: Improves accessibility and SEO.

How:

• Add descriptive alt text when uploading
• Edit alt text in asset details
• Make alt text meaningful, not just a filename

4. Organize with Consistent Naming

Why: Easier to search and filter assets.

How:

• Use consistent naming conventions
• Group related assets with prefixes: blog-, product-, team-
• Include dates if relevant: 2025-11-26-event-photo.jpg

5. Clean Up Unused Assets

Why: Reduces storage costs and clutter.

How:

• Regularly review and delete unused assets
• Use bulk select to remove multiple files
• Check for assets not linked to any content

6. Use Cloud Storage for Production

Why: Better performance and scalability.

How:

• Use local storage for development
• Switch to S3 or S3-compatible storage for production
• Configure CDN for even better performance

7. Set Appropriate File Size Limits

Why: Prevents server issues and slow uploads.

How:

• Set reasonable limits in .env
• Consider your hosting plan's limits
• Balance between flexibility and performance

8. Backup Your Assets

Why: Protects against data loss.

How:

• Regular backups of local storage
• S3 buckets have built-in versioning
• Consider automated backup solutions

Troubleshooting

Problem: Upload Fails with "File Too Large"

Possible causes:

1. File exceeds MAX_FILE_SIZE in .env
2. File exceeds PHP upload_max_filesize
3. File exceeds PHP post_max_size

Solutions:

• Check file size against limits
• Increase MAX_FILE_SIZE in .env
• Update PHP upload_max_filesize and post_max_size
• Restart web server after PHP changes

Problem: S3 Upload Fails

Possible causes:

1. Incorrect AWS credentials
2. IAM user lacks permissions
3. Bucket doesn't exist or wrong region
4. Incorrect endpoint URL

Solutions:

• Verify AWS credentials in .env
• Check IAM user has required permissions
• Confirm bucket name and region are correct
• Verify AWS_ENDPOINT is correct for S3-compatible services

Problem: Assets Not Appearing After Upload

Possible causes:

1. Storage disk not configured correctly
2. File permissions issue (local storage)
3. S3 bucket permissions issue

Solutions:

• Check Project Settings → Default Storage is set correctly
• Verify file permissions on server (local storage)
• Check S3 bucket policy allows uploads
• Review upload logs for errors

Problem: Assets Not Loading (404 Errors)

Possible causes:

1. Wrong storage URL configured
2. S3 bucket not publicly accessible
3. CDN not configured correctly

Solutions:

• Verify AWS_URL points to correct location
• Check S3 bucket public access settings
• Ensure CloudFront distribution is active (if using)
• Test asset URL directly in browser

Problem: Thumbnails Not Generating

Possible causes:

1. Image processing library not installed
2. Unsupported image format
3. Server memory limits

Solutions:

• Install GD or Imagick PHP extension
• Check image format is supported
• Increase PHP memory limit if needed

Next Steps

Now that you understand media and storage management in ElmapiCMS, you can:

• Upload Your First Assets - Start building your media library
• Configure Cloud Storage - Set up S3 for production use
• Use Assets in Content - Link media to your content entries
• Explore the API - Manage assets programmatically
• Optimize Your Workflow - Implement best practices for your team
• Read the Documentation - Deep dive into Asset Library and Storage Configuration

Conclusion

Effective media and storage management is essential for any content-driven application. ElmapiCMS's Asset Library provides:

• Simple upload and organization
• Flexible storage options (local or cloud)
• Powerful search and filtering
• Easy integration with content
• API access for automation

Whether you're using local storage for development or S3 for production, ElmapiCMS gives you the tools to manage your media efficiently and scale as your needs grow.

Ready to get started? Upload your first asset, configure your storage, and start building your media library!

Need help? Check out the ElmapiCMS Documentation or reach out to [email protected].