URL Aliases
URL aliases let you define short, memorable scheme names that map to full base URLs or source paths. Instead of embedding long CDN or storage URLs into every client request, you register an alias once in server configuration and use the short name in request paths.
Aliases are especially useful to avoid hardcoding full URLs in client code. If you ever need to switch CDN providers, change your base URL, or move files between storage backends, you only need to update the server configuration - no client changes required.
Configuration
Set the PP_URL_ALIASES environment variable to a comma-separated list of name=<target> pairs:
PP_URL_ALIASES=mycdn=https://assets.example.com,thumbs=s3:/thumbnails,assets=local:/static
Supported Target Schemes
Alias targets support three schemes:
| Scheme | Description | Requirement |
|---|---|---|
https:// / http:// | Forward to an HTTP upstream | None |
s3:/ | Forward to the configured S3 source | S3 must be enabled |
local:/ | Forward to the configured local filesystem source | Local source must be enabled |
URL Scheme
To use an alias in a request, use the alias name as the scheme followed by a single slash and the path:
/<params>/aliasname:/path/to/image.jpg
PreviewProxy resolves this by appending the path to the alias target:
aliasname:/path/to/image.jpg -> <target>/path/to/image.jpg
Examples:
With PP_URL_ALIASES=cdn=https://assets.example.com,thumbs=s3:/thumbnails,assets=local:/static:
/w=400/cdn:/products/photo.jpg -> https://assets.example.com/products/photo.jpg
/w=400/thumbs:/banner.jpg -> s3:/thumbnails/banner.jpg (fetched via S3)
/w=400/assets:/logo.png -> local:/static/logo.png (fetched from disk)
Multiple Aliases Example
PP_URL_ALIASES=cdn=https://assets.example.com,thumbs=s3:/thumbnails,assets=local:/static
| Alias | Target | Example Request | Resolves To |
|---|---|---|---|
cdn | https://assets.example.com | /w=400/cdn:/products/photo.jpg | https://assets.example.com/products/photo.jpg |
thumbs | s3:/thumbnails | /h=200/thumbs:/avatars/user1.jpg | s3:/thumbnails/avatars/user1.jpg (via S3) |
assets | local:/static | /assets:/logo.png | local:/static/logo.png (from disk) |
Security
Alias targets are operator-configured and treated as trusted sources. HTTP alias targets bypass private IP blocking, so they can point to internal services (e.g., http://internal-cdn.local/) that would otherwise be blocked by SSRF protection. The PP_ALLOWED_HOSTS allowlist does not apply to alias targets either.
User-supplied URLs (i.e., non-alias requests) are still subject to all SSRF protections.
Reserved Names
The alias names s3 and local are reserved for the built-in S3 and local filesystem sources. Defining an alias with either of these names will have no effect - they will never be reachable as aliases regardless of the PP_URL_ALIASES configuration.