ToFF Form: Troubleshooting & Diagnostic Runbooks

Powered by Formbricks

Managed by CultureOS

This diagnostic manual provides fast-remediation runbooks for addressing operational faults, container restarts, transactional email failures, and asset caching issues in ToFF Form.

System Operations & Engineering

This operational system is configured, deployed, and managed by CultureOS. CultureOS is an AI-native practice helping cultural institutions modernize digital infrastructure, archives, and research workflows responsibly.

Automated System Diagnostics (One-Liner)

Before initiating manual debugging, execute the automated health-check suite on host personal-assistant:

ssh personal-assistant "bash /opt/formbricks/ops/doctor-check.sh"

A normal, healthy system will return:

==========================================================
   🩺 ToFF Form: Production System Health Doctor Check
   Host: personal-assistant (40.160.54.226)
   Domain: https://form.tomoffinland.org
==========================================================
1. Checking Caddy HTTPS Public Endpoint... ✅ PASS (HTTP 200)
2. Checking Local Formbricks Port 3005... ✅ PASS (HTTP 200)
3. Checking Docker Containers (6 Expected)...
   - formbricks-formbricks-1: ✅ PASS (running, health: none)
   - formbricks-cube-1: ✅ PASS (running, health: healthy)
   - formbricks-hub-1: ✅ PASS (running, health: healthy)
   - formbricks-spicedb-1: ✅ PASS (running, health: healthy)
   - formbricks-postgres-1: ✅ PASS (running, health: healthy)
   - formbricks-redis-1: ✅ PASS (running, health: healthy)
4. Checking PostgreSQL Database Connectivity... ✅ PASS
5. Checking Redis Health... ✅ PASS (PONG)
6. Checking Whitelabel Brand Assets (Wordmark SVG)... ✅ PASS (HTTP 200)
==========================================================
🎉 ALL CHECKS PASSED: Exit Code 0 (Production Verified)

Issue 1: Magic Link Emails Not Arriving

Symptom

Users report entering their email at https://form.tomoffinland.org but never receive the sign-in Magic Link.

Diagnostic & Resolution

1. Verify the Resend API key status in /opt/formbricks/.env:

   ssh personal-assistant "grep 'RESEND_API_KEY' /opt/formbricks/.env"

2. Inspect the Hub worker container mail dispatch logs:

   ssh personal-assistant "docker logs --tail=100 formbricks-hub-1 | grep -i 'mail\|smtp\|resend'"

3. If credentials were reset or expired, update the secret in .env and restart the worker:

   ssh personal-assistant "cd /opt/formbricks && docker compose restart formbricks-hub-1"

Issue 2: Old Formbricks Logo Displayed in Browser (Image Cache Lock)

Symptom

The browser displays the generic Formbricks logo instead of the official Tom of Finland handwritten signature mark.

Root Cause

Next.js dynamic image optimizer (/_next/image) marks assets with Cache-Control: public, max-age=31536000, immutable, instructing browsers to ignore server updates for one year.

Resolution

1. Perform a hard browser reload:
   • macOS: Cmd + Shift + R
   • Windows: Ctrl + F5
2. Verify Caddyfile contains the cache bypass stanza:

   ssh personal-assistant "grep -A 8 'formbricks-wordmark' /etc/caddy/Caddyfile"

3. Re-execute the branding injection script:

   ssh personal-assistant "cd /opt/formbricks && bash apply-toff-branding.sh"

Issue 3: Container Restart & Cluster Recovery

Symptom

The public URL returns HTTP 502 Bad Gateway from Caddy.

Resolution

1. Check running containers:

   ssh personal-assistant "docker ps -a --filter 'name=formbricks'"

2. If any container exited unexpectedly:

   ssh personal-assistant "cd /opt/formbricks && docker compose restart"

3. Check PostgreSQL connection readiness:

   ssh personal-assistant "docker exec formbricks-postgres-1 pg_isready -U postgres"

Issue 4: Foundation Typography Not Rendering

Symptom

Headlines fall back to standard serif or sans-serif fonts rather than Tom Slab Medium or Favorit.

Resolution

1. Ensure the static font files are accessible via Caddy:

   curl -sI https://form.tomoffinland.org/fonts/tom-slab-medium.woff2

   Expected response: HTTP/2 200 OK.
2. Verify the CSS chunk contains the @font-face injection:

   ssh personal-assistant "bash /opt/formbricks/apply-toff-branding.sh"