context.md

HuggingPost — Full Context

What it is: Self-hosted Postiz v2.11.3 on Hugging Face Spaces. Social media scheduler with multi-channel posting (8 platforms work immediately, 12+ need OAuth setup).

Architecture:

• HF Space: single public port 7860 (health-server.js)
• Internal: nginx:5000 → Postiz 4 PM2 procs (backend:3000, frontend:4200, workers, cron)
• Postgres + Redis internal
• Optional HF Dataset backup + sync loop

---

Critical Issues Fixed

1. Font build hang (FIXED)

Problem: next build tried to fetch fonts from fonts.gstatic.com → blocked/throttled on HF → timeout → build never completes → container won't start.

Solution: Vendor 4 woff2 files + runtime patch in start.sh:

• Fonts: vendor/fonts/PlusJakartaSans-{500,600}-{normal,italic}.woff2
• Patch script: vendor/patch-jakarta-font.js rewrites two layout.tsx files from next/font/google to next/font/local
• Dockerfile Stage 2: copies fonts + patch script to /opt/vendor/
• start.sh: detects if patch not applied (old cached image), applies it before frontend build

Commit: fd4cae0 (font patch)

2. Blank white page at /app/ (FIXED)

Root cause: HF Spaces reverse proxy intercepts absolute redirects to its own hostname, resolves them server-side, returns 200 (not 307). Next.js redirects to /auth as https://somratpro-huggingpost.hf.space/auth → proxy resolves it → blank 200 page.

Solution: Two fixes in health-server.js + Dockerfile:

1. rewriteLocation() function converts absolute URLs (internal or SPACE_HOST) to relative /app paths so browser does the navigation
2. Nginx patch: fix proxy_set_header X-Forwarded-Proto to use HF proxy's value, not internal scheme

Commits: 57b8b04 (Location rewrite + nginx fix), 245f89d (dashboard rewrite)

3. OAuth client_id=undefined (NOT A BUG)

LinkedIn/X/etc. OAuth links show client_id=undefined because env vars not set as HF Space secrets. User needs to create developer apps, add keys as secrets, restart. New dashboard guides users through this.

---

Files Changed

Dockerfile

• Stage 2, after postiz-builder COPY block: copy vendor fonts + patch script to /opt/vendor/
• nginx.conf patch:
  • Add /app prefix when proxying to Next.js (line 160: proxy_pass http://127.0.0.1:4200/app/;)
  • Fix x-forwarded-proto (line 162: use $http_x_forwarded_proto not $scheme)

start.sh

• Lines 172–187: Runtime font patch block
  • If layout.tsx still has next/font/google, copy fonts, run patch script
  • Idempotent — skips if already patched
  • Happens before next build so no network calls

health-server.js

• getSocialPlatforms() (lines 51–98): Array of all channels with ready status, setup URLs, env var names
  • 8 "works immediately" (Bluesky, Mastodon, Telegram, Dev.to, Hashnode, Nostr, Lemmy, Warpcast)
  • 12 "needs OAuth" (LinkedIn, X, Facebook, Instagram, Threads, YouTube, TikTok, Reddit, Pinterest, Discord, Slack)
• rewriteLocation() (lines 465–505): Converts Location headers from Postiz
  • Matches internal hosts (127.0.0.1, localhost) or SPACE_HOST
  • Converts absolute URLs to /app-prefixed relative paths
• renderDashboard() (lines 176–446): Complete rewrite
  • Open Postiz button (disabled during boot, auto-activates when running)
  • Status badges: Postiz, Uptime, Backup
  • 4-step getting-started guide
  • "Works immediately" section (8 platforms, collapsible)
  • "Needs API keys" section (OAuth platforms, shows count configured, direct links to dev portals)
  • "System & Backup" section (sync status, uptime monitor)
  • Auto-refresh JS every 30s updates button state + badge states
  • Deep-link to HF Space settings using SPACE_ID env var

Vendor files (new):

• vendor/fonts/PlusJakartaSans-500-normal.woff2, -500-italic, -600-normal, -600-italic
• vendor/patch-jakarta-font.js

---

Current State

✅ Working:

• Font patch applied at build time (Dockerfile) + runtime fallback (start.sh)
• Next.js frontend builds successfully (~5 min first boot, <1 min with cached .next from backup)
• Blank /app/ screen fixed — middleware redirects work, browser navigates correctly
• nginx routes work: /api → backend, /uploads → fs, / → frontend
• Dashboard shows platform status, guides users through setup
• HF_TOKEN secret no longer leaks in startup banner

---

Deployment

All changes pushed to:

• GitHub: somratpro/HuggingPost (main branch)
• HF Space: somratpro/HuggingPost (auto-synced)

HF rebuilds automatically when Dockerfile or start.sh changes.