PDFg in ColdFusion 2025
Making PDF generation stable and performant
Last updated: November 12, 202612 min read
ColdFusion's PDF Generation (PDFg) service enables server-side PDF creation and manipulation. Configure PDFg for stability, security, and performance in production environments.
PDFg Architecture
The PDF Service (PDF Service Manager) runs as a separate add-on service that ColdFusion communicates with over HTTP:
- The PDF Service runs independently from the main ColdFusion process
- It backs the
cfhtmltopdftag only;cfdocumentandcfpdfrun inside ColdFusion and don't use it cfhtmltopdfsends HTML to the service, which renders it and returns the PDF- Communication happens over a configurable port (default is 8987)
Installation and Configuration
Install the PDF package using cfpm, then install the add-on services that provide the PDF Service:
Install PDF Support
# Install the PDF package
cfpm install pdf
# The PDF Service (PDFG) used by cfhtmltopdf runs on Jetty and ships
# with Adobe's add-on services (Jetty) installer. Install it, then make
# sure the service is running before verifying it in the Administrator.Then add or verify the service manager in the ColdFusion Administrator under Data & Services > PDF Service (default port 8987).
Isolation for Stability
Best Practice: Run PDFg on separate nodes from your application servers for improved stability and resource isolation.
Running PDFg on separate nodes provides several important benefits:
- PDFg crashes or failures won't affect your main application servers
- Resource-intensive PDF generation is isolated from normal application processing
- You can scale PDFg capacity independently based on document generation workload
- Troubleshooting and monitoring become easier when services are separated
Security Considerations
- Input Validation: Limit and validate untrusted HTML input
- Resource Limits: Prevent resource exhaustion attacks
- Network Access: Restrict PDFg service to internal network only
- IP Filtering: Recent updates add IP-based filtering on the Jetty side; configure the allowed and blocked addresses in
jetty-ipaccess.xmlin the Jettyetcfolder
Secure PDF Generation
<!--- Limit HTML input from untrusted sources --->
<cfif len(userHTML) GT 100000>
<cfthrow message="HTML input too large">
</cfif>
<!--- Sanitize untrusted HTML (AntiSamy-based) --->
<cfset cleanHTML = getSafeHTML(userHTML)>
<!--- Generate PDF through the PDF Service --->
<cfhtmltopdf>
<cfoutput>#cleanHTML#</cfoutput>
</cfhtmltopdf>// Limit HTML input from untrusted sources
if (len(userHTML) > 100000) {
throw(message="HTML input too large");
}
// Sanitize untrusted HTML (AntiSamy-based)
cleanHTML = getSafeHTML(userHTML);
// Generate PDF through the PDF Service
cfhtmltopdf() {
writeOutput(cleanHTML);
}Performance Optimization
- Cache generated PDFs when the source content doesn't change frequently
- Use asynchronous generation for large documents to avoid blocking requests
- Optimize your HTML and CSS for faster rendering performance
- Avoid loading external resources like images and fonts when possible to reduce dependencies
- Configure an appropriate heap size for the PDFg JVM based on your workload
Cache PDF Output
<!--- Cache PDF for 1 hour --->
<cfset pdfCacheKey = "invoice_#invoiceID#">
<cfset cachedPDF = cacheGet(pdfCacheKey)>
<cfif isNull(cachedPDF)>
<cfdocument format="pdf" name="cachedPDF">
<!--- Document content --->
</cfdocument>
<cfset cachePut(pdfCacheKey, cachedPDF, createTimeSpan(0, 1, 0, 0))>
</cfif>
<cfcontent type="application/pdf" variable="#cachedPDF#">// Cache PDF for 1 hour
pdfCacheKey = "invoice_#invoiceID#";
cachedPDF = cacheGet(pdfCacheKey);
if (isNull(cachedPDF)) {
cfdocument(format="pdf", name="cachedPDF") {
// Document content
}
cachePut(pdfCacheKey, cachedPDF, createTimeSpan(0, 1, 0, 0));
}
cfcontent(type="application/pdf", variable=cachedPDF);Update and Regression Testing
PDFg updates may introduce rendering changes that affect your documents:
- Carefully review PDFg update notes for any known regressions or changes
- Test all critical PDF generation functionality after applying updates
- Maintain a comprehensive test suite with sample documents to catch rendering changes
- Monitor production output for rendering differences after updates are deployed
Common PDF Operations
PDF Generation
Generate PDF from HTML
<cfdocument format="pdf" filename="output.pdf" overwrite="true">
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
h1 { color: #333; }
</style>
</head>
<body>
<h1>Invoice #12345</h1>
<p>Details here...</p>
</body>
</html>
</cfdocument>cfdocument(format="pdf", filename="output.pdf", overwrite=true) {
writeOutput("
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
h1 { color: ##333; }
</style>
</head>
<body>
<h1>Invoice ##12345</h1>
<p>Details here...</p>
</body>
</html>
");
}PDF Manipulation
PDF Operations
<!--- Merge PDFs --->
<cfpdf action="merge" destination="merged.pdf" overwrite="true">
<cfpdfparam source="file1.pdf">
<cfpdfparam source="file2.pdf">
</cfpdf>
<!--- Extract pages --->
<cfpdf action="extracttext" source="input.pdf" name="pdfText">
<!--- Add watermark --->
<cfpdf action="addwatermark"
source="input.pdf"
image="watermark.png"
destination="output.pdf">// Merge PDFs
cfpdf(
action="merge",
destination="merged.pdf",
overwrite=true,
source="file1.pdf,file2.pdf"
);
// Extract text
cfpdf(
action="extracttext",
source="input.pdf",
name="pdfText"
);
// Add watermark
cfpdf(
action="addwatermark",
source="input.pdf",
image="watermark.png",
destination="output.pdf"
);Monitoring and Troubleshooting
- Continuously monitor PDFg service health and uptime to catch issues early
- Track PDF generation times using the Performance Monitoring Toolset (PMT)
- Configure alerts to notify you of PDFg service crashes or high error rates
- Regularly review PDFg logs for rendering errors and performance issues
- Test your failover procedures if you're using multiple PDFg nodes
PDFg Checklist
- PDF package installed via cfpm and add-on services installed
- PDFg service running and configured
- PDFg on separate nodes (recommended)
- Input validation for untrusted HTML
- Resource limits and timeouts configured
- PDF caching implemented for static content
- PDFg service health monitored
- Update regression tests in place
Gotchas
- Service Dependency: The PDF Service must be running for cfhtmltopdf; cfdocument and cfpdf work without it
- Rendering Differences: Complex HTML/CSS may render differently than in browsers
- External Resources: External resources (images, fonts) can cause timeouts or failures
- Update Regressions: PDFg updates can introduce rendering regressions
- Memory Usage: Large PDFs consume significant memory - size JVM appropriately
- Resource Exhaustion: Untrusted HTML input can cause resource exhaustion