| name | puppeteer-screenshots |
| description | Capture webpage screenshots using Puppeteer in a managed queue with configurable concurrency and timeout. Use when you need to automate page thumbnail generation, capture visual snapshots of URLs, or manage a screenshot pipeline with retry logic. Triggers include "capture screenshot", "take thumbnail", "screenshot queue", "Puppeteer capture", or any task involving automated webpage 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
GET /api/screenshot/queue
Response:
{
"pending": 8,
"active": 2,
"failed": 3,
"completed": 231,
"workers": 2
}
Retry all failed screenshots
POST /api/screenshot/retry
Re-queue a single bookmark
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:
RUN apk add --no-cache chromium
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
Disable Puppeteer's bundled Chromium download to save image size:
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.
