dockette/docshot repository overview

⁠Dockette / Docshot

📸 One HTTP call turns any document, spreadsheet, deck, e-mail, archive, audio or video into a picture.

🕹 f3l1x.io⁠ | 💻 f3l1x⁠ | 🐦 @xf3l1x⁠

Docshot takes a document URL and returns an image, like an image proxy (imgproxy, Cloudinary) for documents. Output is one page, a contact sheet, or a ZIP of all pages. It reads 300+ formats⁠: PDF, Office, HTML, Markdown, e-mail, images, video, audio, archives, fonts. It runs self-hosted in one container. Use cases: thumbnails, previews, input for vision LLMs.

⁠Quick start

docker run -d \
  -p 3000:3000 \
  -e DOCSHOT_FETCH_ALLOW='^https://example\.com/' \
  dockette/docshot

<img src="http://localhost:3000/render?url=https://example.com/report.docx&preset=thumb">

⁠API

• GET endpoints read the document from a source⁠.
• POST /upload endpoints read it from the request body (a multipart file or a raw body).
• Parameters are listed under common parameters⁠. An unknown or misplaced parameter is a 400.
• Errors are JSON: {"error", "code", "status"}.

⁠GET /render

One page as PNG, JPEG or WebP.

curl 'localhost:3000/render?url=https://example.com/movie.mp4&time=1:23&width=640&format=webp' -o frame.webp

⁠GET /render/grid

A contact sheet of the pages.

curl 'localhost:3000/render/grid?url=https://example.com/deck.pptx&grid=4x3' -o deck.png

⁠GET /render/pages

A ZIP with every page as an image.

curl 'localhost:3000/render/pages?url=https://example.com/report.docx&limit=50' -o report.zip

⁠GET /info

Document metadata as JSON. Takes source parameters only.

curl 'localhost:3000/info?url=https://example.com/report.docx'

⁠POST /upload

POST /upload (one page), /upload/grid, /upload/pages and /upload/info take the same parameters as their GET counterparts, without the source parameters.

curl -F [email protected] localhost:3000/upload/pages -o report.zip

⁠GET /formats

All supported extensions as JSON.

curl localhost:3000/formats

⁠DELETE /cache

Drops the disk cache entries of one source (?url= or ?s3=) or all entries (?all=true). Returns 404 when the disk cache is off.

curl -X DELETE 'localhost:3000/cache?url=https://example.com/report.docx'

⁠Monitoring

curl localhost:3000/readyz

⁠Sources

⁠Common parameters

⁠Storage

?store=s3 saves the rendered result to S3 / MinIO.

• The response is still the image. The X-Stored-As: s3://bucket/key header names the object.
• A later request reuses a stored result made from the same source revision (S3 ETag, or content hash for other sources) without rendering. It answers with X-Cache: store.
• If the write fails, the image is still returned, with an X-Store-Error header.

Location:

• ?s3= source: next to the source object.
• ?url= and POST /upload: in DOCSHOT_STORE_BUCKET, under DOCSHOT_STORE_PREFIX, then the file name (for ?url=: host and path).
• An upload without a file name always uses hash.
• The bucket must be in DOCSHOT_S3_BUCKETS when that is set.

Key layout: ?store=s3:<strategy>, default DOCSHOT_STORE_STRATEGY.

Other options (width, page, format, ...) add a variant to the key, e.g. docs/report.docx.p2-w300.webp.

docker run -d \
  -p 3000:3000 \
  -e DOCSHOT_S3_ENDPOINT=minio:9000 \
  -e DOCSHOT_S3_ACCESS_KEY=... \
  -e DOCSHOT_S3_SECRET_KEY=... \
  -e DOCSHOT_STORE_BUCKET=previews \
  dockette/docshot

curl -i 'localhost:3000/render?s3=docs/report.docx&store=s3:replace&width=300&format=webp'
# X-Stored-As: s3://docs/report.p1-w300.webp

⁠Formats

GET /formats returns this list as JSON. Archives render each file inside through its own pipeline.

⁠Configuration

All settings are environment variables. A value that does not parse (DOCSHOT_TIMEOUT_SECONDS=3m, DOCSHOT_CACHE_TAGS=yes) stops docshot at startup with a message naming the setting.

⁠General

⁠Output

⁠Presets

⁠Cache

⁠Sources

⁠Store

⁠How it works

• A Go server listens on :3000. It runs Gotenberg⁠ in the same container.
• Documents are converted to PDF (LibreOffice, Chromium). PDFium renders the page.
• Images, video and audio go through Go and ffmpeg.
• Truncated or corrupted images show the part that survived, as in a browser.
• JavaScript and network access are off for untrusted input.

⁠Development

make up          # build + start on :9994
make test-unit   # go vet + unit tests
make lint        # gofmt, staticcheck, govulncheck, shellcheck, hadolint
make smoke       # render one page with the built image
make test        # end-to-end checks

Releases are dated YYYY.MM.DD (see VERSION⁠); what changed is in CHANGELOG.md⁠. Image tags:

To release: run make release, add the version's section to CHANGELOG.md, commit and push. CI publishes the image and the GitHub release, with that section as its notes.

See how to contribute⁠ to this package.

This package is currently maintaining by these authors.

⁠

Consider to support⁠ f3l1x. Also thank you for using this package.