puppeteer-screenshots

# puppeteer-screenshots

Managed Puppeteer screenshot queue for capturing webpage thumbnails.

## When to use

- Generating page thumbnails for saved bookmarks
- Capturing visual snapshots of URLs in a queue
- Managing multiple concurrent Puppeteer workers
- Handling screenshot failures with retry logic

## Architecture

The screenshot system runs as part of the bookmark-manager process:

```
POST /api/bookmarks
      |
      v
ScreenshotQueue.enqueue(bookmarkId)
      |
      v
Queue (concurrency=SCREENSHOT_CONCURRENCY)
      |
      v
Puppeteer.launch() -> page.goto(url, {waitUntil:'networkidle2'})
      |
      v
page.screenshot({path, type:'jpeg', quality:80, clip:{width:1280,height:800}})
      |
      v
UPDATE bookmarks SET screenshot_status='done', screenshot_path=...
```

## Configuration

| Variable | Default | Description |
|---|---|---|
| `SCREENSHOT_ENABLED` | `1` | Enable/disable entire pipeline (0/1) |
| `SCREENSHOT_CONCURRENCY` | `2` | Number of parallel Puppeteer instances |
| `SCREENSHOT_TIMEOUT_MS` | `15000` | Navigation timeout per page in ms |
| `PUPPETEER_EXECUTABLE_PATH` | (bundled) | Path to system Chromium binary |

## Queue API

### Check queue status

```bash
GET /api/screenshot/queue
```

Response:
```json
{
  "pending": 8,
  "active": 2,
  "failed": 3,
  "completed": 231,
  "workers": 2
}
```

### Retry all failed screenshots

```bash
POST /api/screenshot/retry
```

### Re-queue a single bookmark

```bash
POST /api/bookmarks/:id/screenshot
```

## Screenshot status values

| Status | Meaning |
|---|---|
| `pending` | Queued, not yet processing |
| `capturing` | Puppeteer is currently navigating the page |
| `done` | Screenshot saved successfully |
| `failed` | Timed out, navigation error, or page load failed |

## Docker - Chromium setup

The Dockerfile installs Chromium via `apk`:

```dockerfile
RUN apk add --no-cache chromium
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
```

Disable Puppeteer's bundled Chromium download to save image size:

```dockerfile
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
```

## Common errors

### Navigation timeout exceeded

Page did not reach `networkidle2` within `SCREENSHOT_TIMEOUT_MS`. Causes:
- Heavy JavaScript on the page
- External resources blocking load
- Network unavailable from container

Fix: Increase `SCREENSHOT_TIMEOUT_MS` or use `waitUntil:'load'` instead.

### net::ERR_CONNECTION_REFUSED

Target URL is not publicly accessible from the container. Private/internal URLs will fail.

### Running without sandbox

In some Docker environments, Chromium requires `--no-sandbox`. Set `PUPPETEER_NO_SANDBOX=1` to add this flag. Only use in trusted environments.

## Storage

Screenshots stored as JPEG (quality 80) at `DATA_DIR/screenshots/{bookmarkId}.jpg`. Served by Express at `/screenshots/:filename` with auth check. Approximate size: 50-200 KB per screenshot. Monitor disk usage if you have many bookmarks.