Stirling-PDF fuer Vibe Factory

Worum’s geht

VF braucht PDF-Werkzeuge (Mergen, Splitten, OCR, Komprimieren, Wasserzeichen). Stirling-PDF ist die fertige Open-Source-Loesung — wir hosten sie auf unserer AWS-Infra in av-production, hinter Cloudflare Access mit Email-Allow-List @vibe-factory.de, erreichbar an https://pdf-vf.agenticventures.de.

Kein eigenes ERP, keine Custom-Logik. Wir liefern: gehosteter Service mit Auth, EU-Daten-Standort, ~22 €/Monat Selbstkosten.

Architektur

Gleicher Stack wie mcp-vf-hosted, aber ohne Scalekit-OAuth — Auth uebernimmt Cloudflare Access direkt am Edge. Trust-Boundary liegt damit nicht im Container, sondern am CF-PoP.

Browser (VF-Mitarbeiter)
  | CF Access Login (Email-OTP @vibe-factory.de)
  v
Cloudflare Edge (pdf-vf.agenticventures.de)
  | TLS + Access-Policy
  v
Cloudflare Tunnel
  | QUIC outbound nach Frankfurt
  v
AWS Fargate Task (av-production, eu-central-1, default-Cluster)
  +-- stirling     (stirlingtools/stirling-pdf:latest, Port 8080)
  +-- cloudflared  (Sidecar)

Container-Sizing: 0.5 vCPU / 2 GB. Stirling braucht RAM fuer LibreOffice + Tesseract bei OCR — cloudflared ist <128 MB. Wenn unter Last OOM: hoch auf 1 vCPU / 4 GB.

Stateless: Hochgeladene PDFs werden nach 30 Min automatisch geloescht (SYSTEM_MAXFILEAGE=30). Kein EFS, kein S3 — alles im Container-Layer der Task.

Repo

• ~/source/apps/stirling-pdf-vf/
  • infra/ — CDK-Stack (StirlingPdfVf in av-production/eu-central-1)
  • README.md — Deploy + Operations
  • docs/ — Detail-Notes

CDK-Stack-File: ~/source/apps/stirling-pdf-vf/infra/lib/stirling-pdf-vf-stack.ts.

Cost

Aktuell Pilot, nicht an VF berechnet. Wenn VF mehr hosted Services bekommt → Hosting-Bundle-Posten in den naechsten Vertrag.

Phasen

Phase 1 — Setup (in Arbeit, 2026-05-12)

• Repo-Skeleton + CDK-Stack
• AWS Secret-Stub angelegt (stirling-pdf-vf/cloudflared-token, ARN endet Fiycl6)
• CDK Stack-File mit echter Secret-ARN gepatcht
• cdk synth clean
• Cloudflare Tunnel + Public Hostname anlegen (Marvin, Browser)
• Cloudflare Access Application + Policy anlegen (Marvin, Browser)
• AWS Secret mit echtem Tunnel-Token befuellen
• cdk deploy --profile av-prod
• Smoke-Test https://pdf-vf.agenticventures.de

Phase 2 — Hardening (nach Live)

• Stirling-Image-Digest pinnen statt :latest (gegen Supply-Chain-Drift)
• Verhalten unter Last messen, ggf. Sizing anpassen
• cloudflared-Image-Digest auf eine neuere Version aktualisieren wenn Stirling stabil

Phase 3 — Wenn VF skaliert

• Mehr VF-User in CF Access Policy aufnehmen
• Ggf. Stirling-Pro-Features evaluieren (gibt Enterprise-Lizenz mit zusaetzlichen Features)

Setup-Schritte fuer Marvin (Cloudflare Dashboard)

Schritt 1: Tunnel anlegen

1. https://one.dash.cloudflare.com/ → Account hello@marvinkuehlmann.com → Networks → Tunnels
2. “Create a tunnel” → Connector-Type: Cloudflared
3. Tunnel name: stirling-pdf-vf
4. Save tunnel
5. Auf der naechsten Seite (“Install and run a connector”) steht der Tunnel-Token (eyJ...). Token kopieren — den brauchen wir gleich.
6. WICHTIG: Marvin gibt mir den Token, ich pack ihn in AWS Secrets Manager. Token nicht ueber unsicheren Kanal weitergeben — am besten direkt in dieser Session.
7. Auf “Next” klicken (Container-Setup uebergehen — wir laufen in Fargate).
8. Public Hostname dranhaengen:
   • Subdomain: pdf-vf
   • Domain: agenticventures.de
   • Service: HTTP localhost:8080
   • Save hostname.

Schritt 2: CF Access Application

1. https://one.dash.cloudflare.com/ → Access → Applications → “Add an application” → Self-hosted
2. Application name: stirling-pdf-vf
3. Session duration: 24h (Default)
4. Application domain: Subdomain pdf-vf / Domain agenticventures.de / Path: leer
5. Identity providers: One-time PIN (Default, kein extra Setup noetig)
6. Policy hinzufuegen:
   • Policy name: vf-team
   • Action: Allow
   • Configure rules: Selector Emails ending in → Value @vibe-factory.de
7. Zweite Policy (optional aber empfohlen):
   • Policy name: admin
   • Action: Allow
   • Selector Emails → Value hello@marvinkuehlmann.com
8. Save application.

Schritt 3: Token in AWS einspeisen + Deploy

Sobald Marvin den Tunnel-Token gegeben hat, mache ich:

aws secretsmanager put-secret-value \
  --profile av-prod \
  --secret-id stirling-pdf-vf/cloudflared-token \
  --secret-string '<TOKEN>'
cd ~/source/apps/stirling-pdf-vf/infra
npx cdk deploy --profile av-prod --require-approval never

Stack-Deploy dauert 3-5 Min. Stirling-Container braucht weitere 60-90s zum vollen Bootup.

Stolperer-Antizipation (aus mcp-vf-hosted-Erfahrung)

• Erst-Deploy crashed wenn Secret leer: ECS resolved secrets:-Mapping beim Container-Start. Token MUSS vor cdk deploy echt sein, nicht der PLACEHOLDER_BEFORE_DEPLOY der heute drinsteht.
• CF Access muss VOR DNS-CNAME stehen: CF macht den CNAME-Eintrag automatisch beim Public-Hostname-Setup im Tunnel. Heisst: in der Sekunde wo Schritt 1.8 fertig ist, ist pdf-vf.agenticventures.de aufloesbar. Wenn Access in Schritt 2 dann noch nicht steht, ist der Service kurzzeitig ohne Auth — zwar mit leerem Backend (Stirling laeuft noch nicht), aber als Habit: Access erst fertig machen, DANN deploy.
• Stirling Startup-Zeit: 60-90s wegen LibreOffice-Init. Wenn ECS Healthcheck zu frueh schlaegt: startPeriod ist auf 90s gesetzt — sollte reichen.

Open Questions

• Will VF Stirling auf eigener Domain (pdf.vibe-factory.de)? Aktuell auf unserer Domain — schneller weil wir die Zone kontrollieren. Migration spaeter trivial: CNAME aendern + CF Access Domain umstellen.
• Wer von VF soll initial Zugang haben? Aktuell Policy @vibe-factory.de allowt alle VF-Email-Adressen. Falls explizite Whitelist gewuenscht: Policy auf Einzel-Emails umstellen.

Related

• mcp-vf-hosted — Schwesterstack (Mono-MCP fuer VF in claude.ai)
• _index — VF-eigene Open-WebUI-Chat-Instanz (Sister-Projekt, in Planung)
• mcp-hosting-aws-ecs-express — Hosting-Pattern (Vorgaenger-Doku)
• vibe-factory — Kunden-File
• Stirling-PDF Doku: https://docs.stirlingpdf.com/