Skip to main content

Docker

The fastest way to run PreviewProxy is with Docker. The official image is published to the GitHub Container Registry.

Quick Start​

docker run -d -p 8080:8080 ghcr.io/vigrise/previewproxy:latest

PreviewProxy will be available at http://localhost:8080.

Test It​

Open the following URL in your browser to resize and convert a public image to WebP:

http://localhost:8080/400x300,webp/https://http.cat/200

The URL format is:

http://localhost:8080/<params>/<source-url>

If the image is displayed in the browser, PreviewProxy is working.

info

On the first request, the image is fetched from the upstream URL and transformed. On subsequent requests, the result is served from cache.

Production Setup​

warning

The configuration above is for local development only. Before deploying to production, you should:

  • Set PP_HMAC_KEY to require signed requests and prevent unauthorized transforms
  • Set PP_ALLOWED_HOSTS to restrict which upstream domains can be proxied

See the Environment Variables reference for the full list of options.

Docker Compose Example​

A more complete setup using Docker Compose:

services:
  previewproxy:
    container_name: previewproxy
    image: ghcr.io/vigrise/previewproxy:latest
    restart: unless-stopped
    ports:
      - 8080:8080
    environment:
      # Cache tuning
      PP_CACHE_MEMORY_MAX_MB: 512
      PP_CACHE_DISK_MAX_MB: 4096
      PP_CACHE_DIR: /cache
      # Local source
      # PP_LOCAL_ENABLED: true
      # PP_LOCAL_BASE_DIR: /local
    volumes:
      - ./previewproxy_cache:/cache
      # - /path/to/local/files:/local:ro
    logging:
      driver: "json-file"
      options:
        max-size: "10m"

PreviewProxy will be available at http://localhost:8080.

tip

Mount a named volume for PP_CACHE_DIR so the disk cache survives container restarts.

For all available configuration options, see the Environment Variables reference. To enable S3 or local filesystem sources, see S3 Source and Local Filesystem Source.