Configuration

Screengrabber is configured entirely through environment variables. In Docker Compose these go in the environment block; in a .env file they are picked up automatically.

Environment Variables

Variable	Default	Description
REDIS_CONNECTION	localhost:6379	StackExchange.Redis connection string for the screenshot cache.
API_KEYS	(empty)	Comma-separated list of valid API keys. When empty, authentication is disabled.
SCREENSHOT_CACHE_TTL_HOURS	24	How long cached screenshots are retained in Redis, in hours.
SCREENSHOT_CONCURRENCY	4	Maximum number of simultaneous Playwright page captures.

Redis

Screengrabber uses Redis as a read-through cache. If the Redis connection fails at request time, the failure is surfaced as a warning and the screenshot is captured fresh, the service degrades gracefully rather than returning an error.

This architecture choice means that if you don't need caching, you can still run the service without Redis by pointing REDIS_CONNECTION at a Redis instance that may or may not be available.

API Keys

API_KEYS accepts a comma-separated list. Whitespace around each key is trimmed. To rotate keys, update the list and restart the container. The keys are read once at startup.

API_KEYS=key-one,key-two,key-three

If you leave API_KEYS empty the service accepts all requests without authentication, which is suitable for air-gapped, trusted-network deployments, if you're using a reverse proxy with authentication, if you have a firewall that restricts access, or if you don't care about who can use the service.

Concurrency

SCREENSHOT_CONCURRENCY controls how many browser page contexts can run in parallel. Each concurrent capture uses a separate Playwright page inside a single long-lived Edge browser instance. Increase this for higher throughput at the cost of more memory; the right value depends on your host's available RAM.

Example docker-compose.yml

services:
  screengrabber:
    image: ghcr.io/homotechsual/screengrabber:latest
    restart: unless-stopped
    environment:
      REDIS_CONNECTION: redis:6379
      API_KEYS: ${API_KEYS}
      SCREENSHOT_CACHE_TTL_HOURS: 24
      SCREENSHOT_CONCURRENCY: 4
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    restart: unless-stopped