GitHub Pages documentation

PDF generation for AWS-first teams, without a second deployment story.

folio runs from the same container image in AWS Lambda or plain Docker, stores output in S3, and exposes HTML-to-PDF plus PDF operations through a single Fastify API.

Read the API reference Start locally

Reference

API-first docs

Endpoint docs live in a dedicated reference page with request bodies, response examples, auth behavior, and route-specific notes.

Open API reference

Local dev

One compose file

Spin up the API and MinIO locally, generate a PDF, then test the rest of the routes against the same storage flow used in production.

View quick start

Operations

Built for AWS paths

The repo includes SAM deployment, Docker support, auth, metrics, and a smoke test flow so the service is ready for hosted use, not only demos.

Read deployment notes

Quick start

Start locally in a few commands

The local stack uses MinIO for S3-compatible storage and keeps the presigned URLs host-reachable from your browser.

# Copy and edit environment variables
cp .env.example .env

# Optional: local SAM deploy config
cp samconfig.example.toml samconfig.toml

# Start API + MinIO (local S3)
docker compose up

# Generate a PDF
curl -s -X POST http://localhost:8080/pdf/generate \
  -H "Content-Type: application/json" \
  -d '{"html":"<html><body><h1>Hello</h1></body></html>"}' | jq .

Runtime model

One image, two targets

The same container image runs in Lambda or as a regular Docker service. PDF bytes go directly to S3, which keeps the service aligned with Lambda’s ephemeral filesystem model.

Current routes

Core endpoints

GET /health and GET /metrics
POST /pdf/generate
GET /pdf/:id and DELETE /pdf/:id
POST /pdf/merge, /pdf/split, /pdf/compress, /pdf/pdfa

Deployment

Ship to Lambda or any Docker host

The same container image deploys to AWS Lambda via SAM or runs as a plain Docker service on ECS, Fly.io, Railway, or any host with Docker.

# AWS Lambda (SAM)
sam build
sam deploy

# Docker — anywhere
docker run -p 8080:8080 --env-file .env \
  ghcr.io/alegerber/folio:latest

Lambda

SAM + GitHub Actions

Every merge to main triggers sam build → sam deploy → smoke test. Auth uses GitHub OIDC → AWS STS. Recommended: 2048 MB memory, 120 s timeout.

Docker

Build or pull from GHCR

Prebuilt images are published on every release. Tags: latest, x.y.z, x.y. Pass your env vars and run on any container platform.