# Everything about persistent volumes

> Persistent volumes allow your application to store files that persist across deployments and container restarts, essential for user-uploaded content and generated files.

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`.