Everything about persistent volumes

2 min read Updated 1 month ago

Persistent volumes

Persistent volumes allow your application to store files that persist across deployments and instance restarts. This is essential for user-uploaded content, generated files, and any data that needs to survive application updates.

When to use persistent volumes

Do use persistent volumes for:

  • User-uploaded files (profile pictures, documents, media)
  • Generated files that should persist (exports, reports, invoices)
  • Application cache that improves performance
  • Log files you want to preserve between deployments

Don't use persistent volumes for:

  • Application code (use version control instead)
  • Configuration files (use environment variables)
  • Database data (use database services)
  • Temporary files that can be regenerated

Laravel-specific guidelines

For Laravel applications, you should typically only create persistent volumes for directories containing user-generated content:

  • /storage/app - User uploads and application-generated files
  • /storage/logs - Application logs (if you need to preserve them)
  • /public/uploads - Publicly accessible uploads

Important: Avoid creating volumes for these Laravel directories:

  • /bootstrap/cache - Can be regenerated automatically
  • /storage/framework - Contains temporary cache and session files
  • /vendor - Installed via composer during deployment

Critical warning about volume behavior

⚠️ Important: When you create a persistent volume for a directory, it completely replaces that directory's contents.

This means:

  • Any existing files in that directory will be lost
  • The volume starts empty on first creation
  • You cannot access files that were in the original directory

Example scenario: If your Laravel application has files in /storage/app from your git repository, and you create a persistent volume for /storage/app, those original files will no longer be accessible. The directory will be empty until your application writes new files to it.

How to configure persistent volumes

  1. Navigate to your application's settings page
  2. Scroll to the "Storage" section
  3. Click "Add volume"
  4. Enter the size in GB (1-1000)
  5. Enter the path (e.g., /storage/app)
  6. Save your changes

Note: All paths are automatically prefixed with /var/www/html if not already present. For example, /storage becomes /var/www/html/storage.