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.

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.