bagose/html-to-pdf-api repository overview

docker pull bagose/html-to-pdf-api:latest

docker-compose up -d

# Install dependencies
npm install

# Start development server with hot-reload
npm run dev

# Or start production
npm start

# Server
PORT=3000
MAX_BODY_SIZE=10mb
AUTO_CLEANUP_HOURS=24

# Security (⚠️ Change in production!)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123
JWT_SECRET=html-to-pdf-secret-key-change-in-production
SIGNED_URL_SECRET=signed-url-secret-change-me
SIGNED_URL_EXPIRY_MINUTES=60
CORS_ORIGINS=*

# Browser
PUPPETEER_EXECUTABLE_PATH=    # Auto-detected
BROWSER_POOL_SIZE=1

# Queue
QUEUE_CONCURRENCY=3

# Email (optional)
SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
SMTP_FROM=

# Cloud Storage — S3-compatible (optional)
STORAGE_PROVIDER=local
STORAGE_ENDPOINT=
STORAGE_BUCKET=
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY=
STORAGE_SECRET_KEY=
STORAGE_PATH_PREFIX=
STORAGE_KEEP_LOCAL=true

{
  "source_type": "html",
  "source": "<h1>Monthly Report</h1><p>Generated on 2026-02-13</p>",
  "options": {
    "pageSize": "a4",
    "margin": { "top": "20mm", "bottom": "20mm", "left": "15mm", "right": "15mm" }
  }
}

{
  "source_type": "url",
  "source": "https://github.com",
  "output": "image",
  "options": { "format": "png", "fullPage": true }
}

{
  "source_type": "template",
  "source": "indomaret",
  "data": {
    "store_name": "My Store",
    "cashier": "John",
    "items": [
      { "name": "Coffee", "qty": 2, "price": 15000 },
      { "name": "Bread", "qty": 1, "price": 12000 }
    ],
    "payment": 50000
  }
}

{
  "source_type": "html",
  "source": "<h1>Sales Dashboard</h1>",
  "options": {
    "pageSize": "a4",
    "chart": {
      "data": {
        "type": "bar",
        "data": {
          "labels": ["Q1", "Q2", "Q3", "Q4"],
          "datasets": [{
            "label": "Revenue ($K)",
            "data": [120, 190, 150, 210],
            "backgroundColor": ["#6366f1", "#8b5cf6", "#a78bfa", "#c4b5fd"]
          }]
        }
      },
      "width": 700,
      "height": 350
    }
  }
}

{
  "source_type": "html",
  "source": "<h1>Official Document</h1><p>Content here...</p>",
  "options": {
    "pageSize": "a4",
    "qr_code": {
      "text": "https://verify.example.com/doc/12345",
      "position": "bottom-right",
      "label": "Scan to verify"
    },
    "watermark": { "text": "CONFIDENTIAL", "opacity": 0.08 }
  }
}

{
  "source_type": "html",
  "source": "<h1>Product Label</h1>",
  "options": {
    "pageSize": "label",
    "barcode": {
      "text": "SKU-999-XYZ",
      "type": "code39",
      "position": "bottom-center",
      "width": 2,
      "height": 40,
      "displayValue": true
    }
  }
}

{
  "source_type": "template",
  "source": "indomaret",
  "data": {
    "store_name": "My Coffee Shop",
    "items": [{ "name": "Espresso", "qty": 2, "price": 35000 }],
    "payment": 100000
  },
  "options": {
    "pageSize": "thermal_80mm",
    "qr_code": { "text": "ORDER-12345", "position": "bottom-center" },
    "watermark": {
      "text": "My Coffee Shop",
      "repeat": true,
      "opacity": 0.08
    }
  }
}

{ "action": "compress", "filename": "report.pdf", "options": { "quality": "ebook" } }

{ "action": "merge", "files": ["cover.pdf", "chapter1.pdf", "chapter2.pdf"] }

{ "action": "encrypt", "filename": "contract.pdf", "options": { "password": "s3cur3!" } }

{
  "action": "sign",
  "filename": "contract.pdf",
  "options": {
    "signature_name": "ceo",
    "position": "bottom-right",
    "width": 150,
    "height": 75,
    "page": 0
  }
}

{ "action": "extract", "filename": "book.pdf", "options": { "pages": [0, 1, "5-10"] } }

{ "action": "metadata", "filename": "document.pdf" }

{
  "action": "metadata",
  "filename": "report.pdf",
  "options": { "title": "Annual Report 2025", "author": "Finance Team" }
}

{
  "action": "email",
  "filename": "invoice.pdf",
  "options": {
    "to": "[email protected]",
    "subject": "Your Invoice",
    "message": "Please find your invoice attached."
  }
}

{
  "action": "thumbnail",
  "filename": "presentation.pdf",
  "options": { "width": 300, "page": 1, "format": "png" }
}

POST /queue
{ "type": "render", "data": { "html_content": "<h1>Heavy Report</h1>", "options": { "pageSize": "a4" } }, "priority": 5 }

GET /jobs/{job_id}

GET /queue/stats

{
  "html_content": "<div>My receipt HTML</div>",
  "page_size": "thermal_80mm",
  "qr_code": { "text": "INV-001", "position": "bottom-center" }
}

{
  "template": "indomaret",
  "data": {
    "store_name": "Toko Jaya",
    "items": [{ "name": "Mie Instan", "qty": 3, "price": 3500 }],
    "payment": 15000
  }
}

version: "3.8"
services:
  html-to-pdf-api:
    build: .
    image: bagose/html-to-pdf-api:7.2.1
    ports:
      - "3000:3000"
    environment:
      - ADMIN_PASSWORD=your_secure_password
      - JWT_SECRET=your_jwt_secret
      - SIGNED_URL_SECRET=your_signed_url_secret
    volumes:
      - pdf_output:/app/output
      - pdf_data:/app/data
    deploy:
      resources:
        limits:
          memory: 1G

volumes:
  pdf_output:
  pdf_data:

├── server.js              # Entry point & graceful shutdown
├── src/
│   ├── app.js             # Express setup, middleware, security
│   ├── config.js          # Environment configuration & constants
│   ├── swagger.js         # OpenAPI 3.0 documentation
│   ├── admin/
│   │   └── index.html     # Admin dashboard SPA
│   ├── routes/
│   │   ├── index.js       # Route aggregator
│   │   ├── universal.js   # Core: /render, /pdf-action, /queue
│   │   ├── files.js       # File management
│   │   ├── admin.js       # Admin endpoints
│   │   └── health.js      # Health check
│   ├── services/
│   │   ├── renderer.js    # Puppeteer rendering engine
│   │   ├── browser.js     # Browser pool management
│   │   ├── pdfUtils.js    # Merge, protect, compress
│   │   ├── pdfAdvanced.js # Split, extract pages
│   │   ├── pdfMetadata.js # Read/write PDF metadata
│   │   ├── signature.js   # Digital signature stamps
│   │   ├── chart.js       # Chart.js rendering
│   │   ├── table.js       # Auto-paginated tables
│   │   ├── qrBarcode.js   # QR code & barcode generation
│   │   ├── thumbnail.js   # PDF thumbnail generation
│   │   ├── email.js       # SMTP email service
│   │   ├── queue.js       # In-memory job queue
│   │   ├── cloudStorage.js# S3-compatible cloud upload
│   │   ├── signedUrl.js   # Signed URL generation
│   │   ├── fileManager.js # File operations & cleanup
│   │   ├── stats.js       # Request statistics
│   │   ├── apiKey.js      # API key management
│   │   ├── settings.js    # Runtime settings
│   │   └── customTemplate.js # Custom template CRUD
│   ├── templates/         # Built-in receipt & document templates
│   ├── middleware/         # Auth, rate limiting, sanitization
│   └── utils/             # Response helpers, formatters
├── docker-compose.yml
├── Dockerfile
└── package.json

# Basic render test
curl -X POST http://localhost:3000/render \
  -H "Content-Type: application/json" \
  -d '{"source_type":"html","source":"<h1>Test</h1>","options":{"pageSize":"a4"}}'

# Health check
curl http://localhost:3000/health

# List templates
curl http://localhost:3000/templates