Stage File Proxy
Automatically fetches files from a production server on demand for development environments, eliminating the need to sync large file directories.
stage_file_proxy
Install
composer require 'drupal/stage_file_proxy:^3.1'
Overview
Stage File Proxy is an essential development tool that solves a common problem in Drupal development workflows: the need to have production files available in development environments without manually copying potentially gigabytes of user-uploaded content.
When a file is requested that doesn't exist locally, Stage File Proxy intercepts the request and downloads the file from the configured origin server (typically production) in real-time. The file is then saved locally for subsequent requests, creating an efficient on-demand file synchronization system.
The module is particularly intelligent about image styles - when configured, it fetches the original image rather than processed derivatives, allowing Drupal's image system to generate the appropriate style locally. This approach speeds up future requests for other styles of the same image.
For scenarios where local storage isn't needed, Stage File Proxy can operate in "hotlink" mode, simply redirecting requests to the production server via HTTP 301 responses.
Features
- On-demand file fetching from a remote production server when files are missing locally
- Automatic downloading and local caching of remote files for subsequent requests
- Intelligent image style handling that fetches original images and lets the local site generate derivatives
- Hotlink mode for serving files directly from the origin server via 301 redirects
- SSL certificate verification control for HTTPS connections
- Support for HTTP Basic Authentication credentials embedded in the origin URL
- Configurable origin directory for multisite installations with different paths
- File extension exclusion to skip certain file types from proxying
- Custom HTTP headers support for requests to the origin server
- Drush command for bulk downloading all managed files from the origin
- Event system allowing other modules to exclude specific paths from proxying
- Retry mechanism for image style generation during parallel requests
- Protection against CSS/JS aggregation files being proxied
- Directory traversal attack prevention
Use Cases
Local Development Without File Sync
The primary use case: developers working locally can access all production files without downloading gigabytes of user content. Simply configure the production URL as the origin, and files are fetched on-demand as pages are viewed. This significantly reduces local environment setup time and disk space usage.
Staging Environment File Access
Staging environments that need access to production files but shouldn't store duplicates can use Stage File Proxy to fetch files as needed, keeping staging environments lean while still functional for testing.
Hotlink Mode for Limited Storage
When local storage is severely limited or files are only needed temporarily, enable hotlink mode to redirect all file requests to production. No files are stored locally; the production server handles all file serving. Note: this increases load on the production server.
Multisite Development
For multisite installations where each site has different file paths (e.g., sites/site1/files vs sites/site2/files), configure the origin_dir to match the production site's file path, allowing proper file proxying regardless of local path differences.
Bulk File Synchronization
When you need all files locally (e.g., before going offline), use the Drush command 'drush stage_file_proxy:dl' to download all managed files at once, rather than waiting for on-demand fetching.
Excluding Large Media Files
If your site has large video or audio files that you don't want to proxy, configure excluded_extensions with 'mp4,mp3,ogg,webm' to skip these files while still proxying images and documents.
Tips
- Always configure Stage File Proxy in settings.php or settings.local.php rather than through the UI to prevent configuration from being synced to production
- Use Configuration Split module if you need UI configuration and config sync together
- For faster initial setup, run 'drush stage_file_proxy:dl' to download all files at once rather than waiting for on-demand fetching
- Enable 'Image style Root' to download original images once and let your local site generate all needed derivatives
- Monitor Drupal logs for Stage File Proxy errors when debugging file fetching issues
- Remember to update NGINX configuration if you're not using Apache - the default NGINX Drupal config bypasses PHP for file 404s
Technical Details
Admin Pages 1
/admin/config/system/stage_file_proxy
Configure the connection to the origin server and control how files are fetched and handled. This page allows administrators to set up the production server URL, control SSL verification, configure image style handling, and manage file exclusions.
Permissions 1
Drush Commands 1
drush stage_file_proxy:dl
Downloads all managed files from the origin server that don't exist locally. Queries the file_managed table and attempts to download each missing public file.
Troubleshooting 6
Verify the origin URL is correct and accessible. Check that the origin doesn't have a trailing slash. Ensure the origin server allows requests from your development IP. Check Drupal logs for specific error messages from Stage File Proxy.
Update NGINX configuration to route all file requests through Drupal. Change 'location ~ ^/sites/.*/files/styles/' to 'location ~ ^/sites/.*/files/' and ensure it uses 'try_files $uri @rewrite;'.
If the origin has a valid SSL certificate, ensure your server's CA certificates are up to date. For development with self-signed certificates, disable SSL verification by setting 'verify' to FALSE (not recommended for production-like environments).
Ensure 'Image style Root' is enabled so Stage File Proxy fetches original images instead of derivatives. Clear caches and verify the Image module is working correctly. Check file permissions on the styles directory.
Ensure credentials are URL-encoded in the origin URL. Special characters like & must be encoded (e.g., %26). Format: 'http://username:password@example.com'.
Stage File Proxy includes retry logic for image style generation, but heavy concurrent loads may still cause issues. Consider using a reverse proxy or CDN to combine duplicate requests, or pre-warm caches using the Drush download command.
Security Notes 6
- This module should NEVER be enabled on production environments - it creates a dependency on an external server and could expose internal file paths
- The origin URL may contain authentication credentials - ensure settings.php has appropriate file permissions and is not exposed through version control
- If using HTTP Basic Auth in the origin URL, credentials are stored in plain text in configuration
- Verify SSL should remain enabled in staging environments to ensure origin server authenticity
- The module includes protection against directory traversal attacks by rejecting paths containing '..'
- Be cautious with hotlink mode as it exposes your production server URL structure to end users