Skip to main content

Docker

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

Run with Docker​

The only required environment variables to get started are PORT and APP_ENV:

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e APP_ENV=development \
  ghcr.io/vigrise/previewproxy:latest

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

Test It​

Send a request to resize and convert a public image to WebP:

curl "http://localhost:8080/w=400,format=webp/https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png"

The URL format is:

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

If the image is returned successfully, 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 HMAC_KEY to require signed requests and prevent unauthorized transforms
  • Set ALLOWED_HOSTS to restrict which upstream domains can be proxied

See the Environment Variables reference for details.

Docker Compose Example​

A more complete setup using Docker Compose:

services:
  previewproxy:
    image: ghcr.io/vigrise/previewproxy:latest
    ports:
      - "8080:8080"
    environment:
      PORT: "8080"
      APP_ENV: production

      # Security
      HMAC_KEY: "your-secret-hmac-key"
      ALLOWED_HOSTS: "images.example.com,cdn.example.com"

      # Cache tuning
      CACHE_MEMORY_MAX_MB: "512"
      CACHE_DISK_MAX_MB: "4096"
      CACHE_DIR: /cache

      # S3 source (disabled by default)
      S3_ENABLED: "false"

    volumes:
      - previewproxy-cache:/cache
    restart: unless-stopped

volumes:
  previewproxy-cache:
tip

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