Node.js Docker Server for Heavy Processing

The Node.js server offloads CPU/memory-intensive PDF operations (conversion, export, remediation) from the Cloudflare Worker to a Docker container running native Puppeteer. This eliminates CF Browser Rendering rate limits and provides more headroom for long-running jobs.

Architecture

Browser → CF Worker → nodeProxyMiddleware
                         ↓ (heavy POST + healthy)
                    CF Tunnel → 10.1.1.3:8790
                         ↓
                    Node server (same Hono routes)
                      • storage.objects → R2 via S3 API
                      • storage.kv     → CF KV via REST API
                      • storage.browser → Native Puppeteer
                         ↓
                    Response streams back through CF Worker

Fallback: If the Node server is unhealthy or unreachable, the CF Worker runs the route itself using CF Browser Rendering. The circuit breaker in nodeProxyMiddleware opens after 2 consecutive failures, cooling down for 30 seconds before retrying.

Proxied Routes

Only heavy POST requests are forwarded. Everything else stays on the CF Worker.

Pattern	Description
POST /api/convert/:fileId	PDF-to-HTML conversion
POST /api/export/:fileId/pdf	HTML-to-PDF export
POST /api/remediate/html	Single HTML remediation
POST /api/remediate/batch	Batch remediation
POST /api/remediate/url	URL scan + remediation

Storage Strategy

The Node server accesses the same data as the CF Worker — same R2 bucket, same KV namespace — through different APIs.

Need	CF Worker	Node Server
Object storage (files, ZIPs)	R2 binding	R2 via S3-compatible API
Key-value (metadata, status)	KV binding	CF KV via REST API
Browser (PDF gen, screenshots)	CF Browser Rendering	Native Puppeteer

Why this works

• R2 natively supports the S3 protocol. The R2ObjectStorage class uses @aws-sdk/client-s3 pointed at https://{accountId}.r2.cloudflarestorage.com.
• KV is accessible via Cloudflare’s REST API. The CloudflareKvRestStorage class calls https://api.cloudflare.com/client/v4/accounts/{id}/storage/kv/namespaces/{ns}/values/{key}.
• Puppeteer runs natively in the Docker container (the base image ships Chromium). Reuses the existing AwsBrowserProvider from providers/aws.ts.

Key Files

File	Purpose
workers/api/src/server.ts	Node.js HTTP entry point (Hono + @hono/node-server)
workers/api/src/providers/node-server.ts	R2ObjectStorage, CloudflareKvRestStorage, KV namespace shim, factory
workers/api/src/middleware/node-proxy.ts	CF Worker middleware that forwards requests
workers/api/src/services/node-proxy.ts	Proxy logic, health checker, circuit breaker
workers/api/Dockerfile	Docker image based on ghcr.io/puppeteer/puppeteer:latest
docker-compose.yml	Single api-node service on port 8790
.env.node-server.example	Template for all required environment variables
workers/api/tsconfig.node.json	Node-specific TypeScript config (IDE only — tsx ignores it)

How Auth Works

The proxy forwards the Authorization header as-is. The Node server’s requireAuth middleware validates the JWT using SUPABASE_JWT_SECRET. Both CF and Node independently verify the token — double validation is safe.

KV Namespace Shim

Some routes pass c.env directly and access env.KV_SESSIONS (e.g., extractTablesWithVision in convert.ts). The createKvNamespaceShim() function returns an object matching the CF KVNamespace get/put/delete shape, backed by the REST API. The server’s storage middleware injects this shim into c.env.KV_SESSIONS.

Local Development

Run the Node server locally (requires env vars set):

cd workers/api
PORT=8790 tsx src/server.ts

Or with file watching:

cd workers/api
PORT=8790 npm run server:dev

To test the full proxy flow locally, set NODE_API_URL=http://localhost:8790 in wrangler.toml [vars] and run wrangler dev alongside the Node server.

---

Deployment

Prerequisites

• Docker and Docker Compose on 10.1.1.3
• SSH access: ssh -i ~/.ssh/nightly-audit larry@10.1.1.3
• Cloudflare Tunnel configured on the server

Step 1: Create R2 S3 API Token

1. Go to Cloudflare Dashboard > R2 > Manage R2 API Tokens
2. Click Create API token
3. Permissions: Object Read & Write
4. Specify bucket: accessible-pdf-files
5. Save the Access Key ID and Secret Access Key

Step 2: Create CF API Token for KV

1. Go to Cloudflare Dashboard > My Profile > API Tokens
2. Click Create Token
3. Use Custom token template
4. Permissions: Account > Workers KV Storage > Edit
5. Save the token

Step 3: Configure Environment

On 10.1.1.3, in the project directory:

cp .env.node-server.example .env.node-server

Fill in all values:

Variable	Source
R2_ACCOUNT_ID	Cloudflare dashboard > Account ID (sidebar)
R2_ACCESS_KEY_ID	From Step 1
R2_SECRET_ACCESS_KEY	From Step 1
R2_BUCKET_NAME	accessible-pdf-files
CF_ACCOUNT_ID	Same as R2_ACCOUNT_ID
CF_API_TOKEN	From Step 2
KV_SESSIONS_NAMESPACE_ID	9d39d6e609b945848f5082cea23306b0 (from wrangler.toml)
SUPABASE_URL	Supabase project settings
SUPABASE_SERVICE_ROLE_KEY	Supabase project settings > API
SUPABASE_JWT_SECRET	Supabase project settings > API > JWT Secret
ANTHROPIC_API_KEY	Anthropic console
Other API keys	As needed for enabled parsers

Step 4: Build and Start

docker compose up -d --build

Verify it’s running:

docker compose ps
curl http://localhost:8790/health

Expected response:

{
  "success": true,
  "data": { "status": "healthy", "platform": "node-server", "uptime": 5.123 }
}

Step 5: Configure Cloudflare Tunnel

Add a public hostname rule in the Cloudflare Zero Trust dashboard:

Field	Value
Subdomain	node-pdf (or similar)
Domain	anglin.com
Service	http://localhost:8790

This gives the Node server a public URL like https://node-pdf.anglin.com.

Step 6: Set NODE_API_URL on CF Worker

wrangler secret put NODE_API_URL --env production
# Enter: https://node-pdf.anglin.com

The CF Worker will now proxy heavy requests to the Node server.

Step 7: Verify End-to-End

1. Proxy active: Trigger a conversion on pdf.anglin.com. Check CF Worker logs for [node-proxy] Proxying POST /api/convert/... and Node server logs for the incoming request.
2. Fallback works: docker compose stop, trigger another conversion. CF Worker logs should show [node-proxy] Node server unhealthy — falling back to CF.
3. Recovery: docker compose start, wait ~30s for circuit breaker cooldown, trigger again. Should route through Node server.

Updating

To deploy a new version after code changes:

ssh -i ~/.ssh/nightly-audit larry@10.1.1.3
cd /path/to/accessible-pdf-converter
git pull
docker compose up -d --build

Monitoring

• Health check: The Dockerfile includes a HEALTHCHECK that hits /health every 30s. Docker will mark the container as unhealthy if it fails 3 times.
• Logs: docker compose logs -f api-node
• Uptime Kuma: Add https://node-pdf.anglin.com/health as a monitored endpoint.

Troubleshooting

Symptom	Likely Cause	Fix
Container starts then exits	Missing required env var	Check docker compose logs api-node for Missing required env var: ...
Health check passes but proxy fails	CF Tunnel not routing	Verify tunnel config in Zero Trust dashboard
KV operations fail with 403	API token lacks permissions	Recreate token with Workers KV Storage: Edit
R2 operations fail with 403	S3 token wrong bucket scope	Recreate R2 API token scoped to accessible-pdf-files
Puppeteer crashes	Out of memory	Increase container memory limit in docker-compose.yml
Circuit breaker stuck open	Node server was down > 30s	It auto-recovers after the 30s cooldown. Force reset by redeploying the CF Worker.