Local Filesystem
The local filesystem source allows PreviewProxy to serve and transform images stored on the same machine (or a mounted volume). This is useful in containerised deployments where images are available on a shared volume, or in development environments where you want to serve local files.
Enabling the Local Source
The local source is disabled by default. Set PP_LOCAL_ENABLED=true and provide a base directory to activate it.
Configuration
| Variable | Description |
|---|---|
PP_LOCAL_ENABLED | Set to true to enable the local filesystem source. |
PP_LOCAL_BASE_DIR | Absolute path to the root directory from which images will be served. |
Example Configuration
PP_LOCAL_ENABLED=true
PP_LOCAL_BASE_DIR=/data/images
URL Scheme
To request a local image, use the local: scheme in the image URL portion of the path. The path after local:/ is treated as relative to PP_LOCAL_BASE_DIR:
/format=webp/local:/products/photo.jpg
Path Resolution
The path in the request is joined with PP_LOCAL_BASE_DIR to produce the final file path on disk.
Example: With PP_LOCAL_BASE_DIR=/data/images:
| Request Path | File Served |
|---|---|
local:/products/photo.jpg | /data/images/products/photo.jpg |
local:/banner.png | /data/images/banner.png |
local:/2024/uploads/avatar.jpg | /data/images/2024/uploads/avatar.jpg |
Full request example:
/format=webp/local:/products/photo.jpg
Security
Path traversal is blocked. Any request that attempts to access a file outside of PP_LOCAL_BASE_DIR - for example using ../ segments - will be rejected with an error. Files outside the configured base directory can never be accessed through the local source.
This protection applies regardless of how the path is encoded in the request URL.