Configuration
Repix is configured via environment variables. Copy .env.example to .env and adjust as needed:
cp .env.example .env
# Edit .env with your settings
Environment Variables
| Variable | Description | Default |
|---|---|---|
PORT | Server port | 3210 |
SOURCE_PREFIX | Source URL prefix when reconstructing image URLs | https:// |
SOURCE_HOSTNAME | Allowed hostnames when SOURCE_PREFIX is unset or https:// (comma-separated) | — |
FETCH_TIMEOUT | Timeout for fetching source images (ms) | 10000 |
CACHE_CONTROL | Cache-Control header value | public, max-age=31536000, immutable |
CORS_ORIGIN | CORS allowed origin | * |
CORS_CREDENTIALS | CORS credentials (true / false) | false |
ALLOW_CUSTOM_TRANSFORMS | Allow custom transformations beyond presets | true |
ALLOW_PRESETS | Include default presets (xs, sm, md, lg, xl, full) | true |
ALLOW_ORIGINAL_IMAGE | Allow /original/{path} to serve unprocessed images | true |
IMAGE_MAX_WIDTH | Maximum image width (pixels) | 2048 |
IMAGE_MAX_HEIGHT | Maximum image height (pixels) | 2048 |
IMAGE_DEFAULT_QUALITY | Default JPEG/WebP quality (1-100) | 85 |
PRESETS | JSON object of custom presets | — |
LOG_OTLP_ENDPOINT | OTLP endpoint for log draining (e.g. Grafana, Datadog) | — |
LOG_OTLP_HEADERS | OTLP request headers (key=value,key2=value2). Use for auth (e.g. PostHog) | — |
LOG_SAMPLING_INFO | Info log sampling rate (0-100%) | 10 |
LOG_SAMPLING_ERROR | Error log sampling rate (0-100%) | 100 |
Presets via Environment
Define custom presets as a JSON object:
PRESETS='{"thumbnail":"w=200,h=200,fit=cover","banner":"w=1024,h=128","avatar":"w=100,h=100,fit=cover,f=webp,q=85"}'
When PRESETS is set, it replaces the default presets. Omit it to keep the built-in defaults below.
Default Presets
When PRESETS is not set, Repix includes these general-purpose presets with incremental sizes for various use cases (icons, thumbnails, cards, galleries, etc.):
| Preset | Value |
|---|---|
xs | w=64,q=85 |
sm | w=128,q=85 |
md | w=256,q=85 |
lg | w=512,q=85 |
xl | w=1024,q=85 |
full | q=85 |
Original Image Endpoint
When ALLOW_ORIGINAL_IMAGE is true, you can serve images without processing:
https://your-domain.com/original/example.com/path/to/image.jpg
This fetches and returns the source image as-is (no resize, format conversion, etc.). Set to false to disable and return 403.
Security: Preset-Only Mode
Restrict image transformations to predefined presets only by setting ALLOW_CUSTOM_TRANSFORMS to false:
ALLOW_CUSTOM_TRANSFORMS=false
PRESETS='{"thumbnail":"w=200,h=200,fit=cover,f=webp,q=85","banner":"w=1024,h=128,fit=cover,f=webp,q=85"}'
When ALLOW_CUSTOM_TRANSFORMS is false, only preset names can be used in URLs. Any custom parameters will return a 403 error.
Logging
Repix uses evlog for structured logging. You can drain logs to OTLP-compatible backends (Grafana, Datadog, Honeycomb, etc.) and configure sampling to reduce volume at scale.
OTLP Endpoint
Set LOG_OTLP_ENDPOINT to send logs to an OTLP HTTP endpoint:
LOG_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
OTEL_EXPORTER_OTLP_ENDPOINT is also supported as a fallback. See evlog OTLP adapter for provider-specific setup (Grafana Cloud, Datadog, etc.).
For providers that require auth (e.g. PostHog), set LOG_OTLP_HEADERS:
LOG_OTLP_ENDPOINT=https://us.i.posthog.com/i
LOG_OTLP_HEADERS="Authorization=Bearer phc_YOUR_PROJECT_TOKEN"
Format: key=value,key2=value2.
Sampling
At scale, use head sampling to keep a percentage of logs per level:
LOG_SAMPLING_INFO=10 # Keep 10% of info logs
LOG_SAMPLING_ERROR=100 # Always keep errors (default)
Errors are always kept by default. See evlog sampling for details.