How to Use Stirling-Tools with Stirling-PDF: A Practical Guide

This guide provides a comprehensive-guide-to-understanding-selecting-and-maintaining-modern-machines/”>comprehensive-content-plan/”>comprehensive walkthrough on using Stirling-Tools and Stirling-PDF for creating, editing, and managing PDFs. We’ll cover Docker deployment, core workflows, and best practices to streamline your PDF processes.

On-Premises Docker Deployment

Deploy Stirling-PDF (API) and Stirling-Tools (CLI) using Docker Engine 20.x+ and Docker Compose 2.x. Expose the API on port 8080 and the admin/UI on port 9090 (configurable in docker-compose.yml). Map the following directories to your host:

• ./data/pdfs (outputs)
• ./config (configuration)
• ./logs (runtime logs)

Here’s a sample docker-compose.yml:

version: '3.8'
services:
stirling-pdf:
image: stirling/pdf:latest
ports:
- "8080:8080"
volumes:
- ./data/pdfs:/app/pdfs
- ./config:/app/config
- ./logs:/var/log/stirling
environment:
- STIRLING_PDF_BASE_URL=http://localhost:8080

stirling-tools:
image: stirling/tools:latest
ports:
- "9090:9090"
volumes:
- ./data/pdfs:/app/pdfs
- ./config:/app/config
- ./logs:/var/log/stirling
environment:
- STIRLING_TOOLS_CLI=true
- STIRLING_ADMIN_PASSWORD=${STIRLING_ADMIN_PASSWORD}

Note: Volumes ensure data persistence across restarts. The API is exposed on port 8080, and the UI/CLI on port 9090. Securely manage the STIRLING_ADMIN_PASSWORD using environment variables or a .env file.

Startup and Verification

1. Navigate to your docker-compose.yml directory.
2. Start the stack: docker-compose up -d
3. Verify containers: docker-compose ps
4. Check readiness: curl -s http://localhost:8080/health (expect a healthy response).

Creating PDFs

Create from Template

Use a template to generate PDFs. For example, to create a PDF from a Markdown file:

stirling-tools create --template standard --title 'Q1 Summary' --content ./content/q1.md --output /data/pdfs/q1-summary.pdf

Batch Creation

Process multiple Markdown files:

for f in ./content/*.md; do
stirling-tools create --template standard --title "${f%.md}" --content "$f" --output "/data/pdfs/${f%.md}.pdf";
done

Template Flexibility

Stirling-Tools offers various templates (templates/technical, templates/brief, templates/press-release).

Editing and Managing PDFs

Annotate and Watermark

stirling-tools edit --input /data/pdfs/q1-summary.pdf --add-watermark 'Draft' --output /data/pdfs/q1-summary-draft.pdf

Overlay Assets

stirling-tools edit --input /data/pdfs/q1-summary-draft.pdf --overlay ./assets/cover.png --output /data/pdfs/q1-summary-cover.pdf

Metadata Maintenance

stirling-tools metadata set --input /data/pdfs/q1-summary-cover.pdf --keywords 'report, summary, Q1' --subject 'Quarterly Review'

Versioning

Preserve a history of edits:

cp /data/pdfs/q1-summary-cover.pdf /data/pdfs/versions/q1-summary-cover-$(date +%Y%m%d-%H%M%S).pdf

Troubleshooting

Container Not Starting

Check logs: docker-compose logs stirling-pdf. Verify directory permissions and paths.

Port Conflicts

Remap ports in docker-compose.yml.

Permissions

Adjust directory permissions: chmod -R 755 ./data ./config ./logs

Data Integrity

Use pdfinfo for regular integrity checks.

Comparison Table

Pros & Cons

Pros

• Full data sovereignty
• Unified toolchain
• Strong automation potential
• Reproducible workflows
• Clear revision histories

Cons

• Higher initial setup overhead
• Ongoing maintenance
• Potentially longer deployment time