fix: move next build to container startup — HF builder cgroup too small

next build for Postiz needs ~4 GB RSS. The HF Space builder has a ~4 GB
cgroup limit, making it impossible to complete in docker build regardless
of heap tuning, single-thread flags, or multi-stage tricks (exit 137).

Solution: don't run next build in the Dockerfile at all. Run it in start.sh
at container startup where the runtime has 16 GB RAM.

Bonuses over the docker-build approach:
- NEXT_PUBLIC_BACKEND_URL is baked with the real SPACE_HOST URL (correct)
instead of localhost (broken) because we now know it at build time
- First boot ~5-8 min; all subsequent boots restore .next from HF Dataset
backup and skip the build entirely

Changes:
- Dockerfile: remove all frontend build steps; back to clean 2-stage;
HEALTHCHECK start-period raised to 600s for first-boot window
- start.sh: build frontend at startup if .next/BUILD_ID absent;
8 GB heap (runtime has 16 GB); shows progress in logs
- postiz-sync.py: include .next (minus webpack cache) in backup tarball;
restore on boot so subsequent starts skip the build;
raise SYNC_MAX_FILE_BYTES default 100→300 MB
- README: document first-boot behavior

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Dockerfile

@@ -1,35 +1,31 @@
 # ============================================================================
 # HuggingPost — Postiz v2.11.3 on Hugging Face Spaces
 #
-# Three-stage build to beat the HF Space builder memory limit:
+# Two-stage build: compile only the server-side apps (backend/workers/cron)
+# during docker build. The Next.js frontend is intentionally NOT built here.
 #
-#   Stage 1 (postiz-builder):   clone → patch → full install →
-#                                build backend + workers + cron
-#   Stage 2 (postiz-frontend):  fresh clone → patch → FILTERED install
-#                                (frontend dep tree only, skips NestJS/
-#                                Prisma/bcrypt/etc.) → build Next.js
-#   Stage 3 (runtime):          COPY server build from Stage 1
-#                                overlay .next from Stage 2
+# Why: `next build` for Postiz needs ~4 GB RSS. The HF Space builder has a
+# ~4 GB cgroup limit, so it always OOMKills the process (exit 137) regardless
+# of heap tuning, parallel/single-thread settings, or multi-stage tricks.
 #
-# Why fresh clone in Stage 2 (not COPY from Stage 1):
-#   COPY --from=stage1 /build /build copies ~2 GB of node_modules (3817
-#   packages). BuildKit decompresses that as a layer; the OS page-caches it.
-#   Then next build loads its own module graph on top. Combined RSS exceeds
-#   the builder cgroup limit → exit 137 OOMKilled.
-#   A filtered pnpm install in a fresh Stage 2 pulls only the frontend
-#   package's npm dependency tree — maybe 30-50% of the full install —
-#   so peak RSS stays within limits.
+# Solution: build the frontend in start.sh at container startup, where the
+# runtime has 16 GB RAM. The compiled .next is included in the HF Dataset
+# backup so subsequent restarts skip the build entirely.
+#
+# First boot:  ~5-8 min (server apps start immediately; frontend compiles in
+#              background, then Postiz frontend process starts when done).
+# Later boots: .next restored from backup → Postiz starts normally (~90 s).
 #
 # Container layout at runtime:
 #   - nginx (port 5000, internal)         — Postiz frontend + backend + uploads
 #   - PM2 → 4 Postiz procs (backend / frontend / workers / cron)
 #   - postgres (port 5432, internal)
 #   - redis    (port 6379, internal)
-#   - postiz-sync.py loop                 — backup DB + uploads to HF Dataset
+#   - postiz-sync.py loop                 — backup DB + uploads + .next
 #   - health-server.js (port 7860, public) — dashboard + reverse proxy
 # ============================================================================
 
-# ── Stage 1: Clone, patch, full install, build server apps ───────────────────
+# ── Stage 1: Clone, patch, install deps, build server apps ───────────────────
 FROM node:22.20-alpine AS postiz-builder
 
 WORKDIR /build
@@ -49,15 +45,14 @@ RUN npm install -g pnpm@10.6.1
 # Pinned to v2.11.3 — last release before Temporal became a hard requirement.
 RUN git clone --depth=1 --branch v2.11.3 https://github.com/gitroomhq/postiz-app.git .
 
-# Patch Next.js config (applied here so Stage 2's fresh clone also patches).
-# Stage 2 re-applies the same sed commands on its own clone.
-#   1. basePath/assetPrefix=/app  → Postiz UI at /app; dashboard owns /
-#   2. productionBrowserSourceMaps: false  → shaves ~500 MB RSS during emit
-#   3. Sentry sourcemap plugin: disable: true  → saves ~300 MB
-#   4. swcMinify: false  → forces Terser (pure JS, V8-heap-bounded) instead
-#      of the native SWC binary that adds RSS outside the V8 heap limit
-#   5. experimental.cpus=1 + workerThreads=false  → single-thread webpack;
-#      no parallel worker copies of the module graph eating extra RAM
+# Patch Next.js config — applied now so the patched file is in the image and
+# `pnpm run build:frontend` in start.sh picks up all settings automatically.
+#   1. basePath/assetPrefix=/app   → Postiz UI at /app; HuggingPost dashboard owns /
+#   2. productionBrowserSourceMaps: false  → smaller build output
+#   3. Sentry sourcemap plugin disabled   → no network calls during build
+#   4. swcMinify: false  → Terser (pure JS) instead of native SWC binary;
+#      avoids extra RSS outside the V8 heap
+#   5. experimental.cpus=1 + workerThreads=false  → single-thread webpack
 RUN sed -i "s|const nextConfig = {|const nextConfig = {\n  basePath: '/app',\n  assetPrefix: '/app',\n  swcMinify: false,|" apps/frontend/next.config.js \
     && sed -i "s|productionBrowserSourceMaps: true|productionBrowserSourceMaps: false|" apps/frontend/next.config.js \
     && sed -i "s|disable: false,|disable: true,|" apps/frontend/next.config.js \
@@ -76,60 +71,20 @@ ENV SENTRY_DSN="" \
     NEXT_TELEMETRY_DISABLED=1 \
     NEXT_PRIVATE_SKIP_SIZE_MINIMIZATION=true
 
-# Full install — backend, workers, cron all need the complete dep tree.
 RUN pnpm install --frozen-lockfile=false
 
-# Build server-side apps only. Frontend is built in its own isolated stage.
+# Build server-side apps. Sequential + 3 GB heap each.
+# Frontend is NOT built here — see start.sh.
 RUN NODE_OPTIONS="--max-old-space-size=3072" pnpm run build:backend
 RUN NODE_OPTIONS="--max-old-space-size=3072" pnpm run build:workers
 RUN NODE_OPTIONS="--max-old-space-size=3072" pnpm run build:cron
 
-# Remove dev artefacts before Stage 3 copies this tree into the runtime image.
+# Clean up dev artefacts before Stage 2 copies this tree into the runtime image.
 RUN find . -name ".git" -type d -prune -exec rm -rf {} + 2>/dev/null || true \
  && rm -rf .github reports Jenkins .devcontainer 2>/dev/null || true
 
 
-# ── Stage 2: Build Next.js frontend with minimal dep tree ────────────────────
-FROM node:22.20-alpine AS postiz-frontend
-
-WORKDIR /build
-
-RUN apk add --no-cache git bash
-RUN npm install -g pnpm@10.6.1
-
-# Fresh clone — gives a clean slate with no Stage 1 memory residue.
-RUN git clone --depth=1 --branch v2.11.3 https://github.com/gitroomhq/postiz-app.git .
-
-# Apply the same patches as Stage 1.
-RUN sed -i "s|const nextConfig = {|const nextConfig = {\n  basePath: '/app',\n  assetPrefix: '/app',\n  swcMinify: false,|" apps/frontend/next.config.js \
-    && sed -i "s|productionBrowserSourceMaps: true|productionBrowserSourceMaps: false|" apps/frontend/next.config.js \
-    && sed -i "s|disable: false,|disable: true,|" apps/frontend/next.config.js \
-    && sed -i "s|experimental: {|experimental: {\n    cpus: 1,\n    workerThreads: false,|" apps/frontend/next.config.js \
-    && grep -q "basePath: '/app'" apps/frontend/next.config.js \
-    && grep -q "swcMinify: false" apps/frontend/next.config.js \
-    && grep -q "cpus: 1" apps/frontend/next.config.js \
-    || (echo "PATCH FAILED — next.config.js shape changed upstream"; exit 1)
-
-ENV SENTRY_DSN="" \
-    SENTRY_AUTH_TOKEN="" \
-    SENTRY_ORG="" \
-    SENTRY_PROJECT="" \
-    NEXT_PUBLIC_SENTRY_DSN="" \
-    NEXT_TELEMETRY_DISABLED=1 \
-    NEXT_PRIVATE_SKIP_SIZE_MINIMIZATION=true
-
-# Filtered install — pulls only packages in the frontend's dependency tree.
-# Skips NestJS, Prisma, bcrypt, Bull, and other server-only packages.
-# Results in a much smaller node_modules → less OS page cache pressure
-# → lower peak RSS during next build.
-RUN pnpm install --filter "./apps/frontend..." --frozen-lockfile=false
-
-# Build Next.js frontend in isolation.
-# Stage 1's processes are dead; Stage 2 starts with a clean address space.
-RUN NODE_OPTIONS="--max-old-space-size=3072" pnpm run build:frontend
-
-
-# ── Stage 3: Runtime ──────────────────────────────────────────────────────────
+# ── Stage 2: Runtime ──────────────────────────────────────────────────────────
 FROM node:22.20-alpine
 
 WORKDIR /app
@@ -159,14 +114,11 @@ RUN pip install --no-cache-dir --break-system-packages \
     huggingface_hub \
     PyYAML
 
-# Copy server build (backend + workers + cron + full node_modules, cleaned).
+# Copy fully-built Postiz server apps + node_modules + patched next.config.js.
+# .next is intentionally absent here; start.sh builds or restores it at boot.
 COPY --from=postiz-builder /build /app
 
-# Overlay the compiled Next.js frontend from the isolated build stage.
-# This overwrites the empty apps/frontend/.next placeholder in the tree above.
-COPY --from=postiz-frontend /build/apps/frontend/.next /app/apps/frontend/.next
-
-# Use upstream's nginx.conf — routes /api→3000, /uploads→fs, /→4200.
+# nginx.conf: routes /api→3000, /uploads→fs, /→4200.
 COPY --from=postiz-builder /build/var/docker/nginx.conf /etc/nginx/nginx.conf
 
 # Health-server outside /app to avoid pnpm workspace collisions.
@@ -192,7 +144,7 @@ RUN chmod +x /opt/start.sh /opt/setup-uptimerobot.sh
 
 EXPOSE 7860
 
-HEALTHCHECK --interval=30s --timeout=10s --start-period=240s --retries=3 \
+HEALTHCHECK --interval=30s --timeout=10s --start-period=600s --retries=5 \
     CMD curl -f http://localhost:7860/health || exit 1
 
 CMD ["/opt/start.sh"]

README.md

@@ -227,8 +227,11 @@ Total resident set ~3–6 GB under typical load — well within HF free tier's 1
 
 ## 🐛 Troubleshooting
 
+**First boot takes 5–8 minutes**
+The Next.js frontend is not compiled during the Docker build (the HF builder's ~4 GB memory limit is less than `next build` needs). Instead it compiles on first container startup where 16 GB is available. Watch `[frontend-build]` lines in the Logs tab. Postiz starts automatically when done. All subsequent restarts are fast — the compiled `.next` is stored in the HF Dataset backup and restored at boot.
+
 **"Postiz backend unavailable" on first load**
-First boot takes 30–90s after the build finishes. Wait for the dashboard to show green badges for both backend and frontend.
+On restarts after the first boot, wait 30–90 s for PM2 processes to come up. Check the dashboard status badges.
 
 **Data lost after restart**
 `HF_TOKEN` is not set, or it doesn't have write access. Add it and the next restart will restore from backup. The backup must have run at least once before the restart.

postiz-sync.py

@@ -46,10 +46,11 @@ HF_TOKEN = os.environ.get("HF_TOKEN")
 HF_USERNAME = os.environ.get("HF_USERNAME")
 DATABASE_URL = os.environ.get("DATABASE_URL", "postgresql://postiz:postiz@localhost:5432/postiz")
 BACKUP_DATASET_NAME = os.environ.get("BACKUP_DATASET_NAME", "huggingpost-backup")
-SYNC_MAX_FILE_BYTES = int(os.environ.get("SYNC_MAX_FILE_BYTES", str(100 * 1024 * 1024)))  # 100 MB
+SYNC_MAX_FILE_BYTES = int(os.environ.get("SYNC_MAX_FILE_BYTES", str(300 * 1024 * 1024)))  # 300 MB
 POSTIZ_HOME = Path(os.environ.get("POSTIZ_HOME", "/postiz"))
 UPLOADS_DIR = Path(os.environ.get("UPLOAD_DIRECTORY", str(POSTIZ_HOME / "uploads")))
 SECRETS_DIR = POSTIZ_HOME / ".secrets"
+NEXT_DIR = Path("/app/apps/frontend/.next")   # compiled frontend; backed up to skip rebuild
 STATUS_FILE = Path("/tmp/sync-status.json")
 
 
@@ -141,6 +142,13 @@ def backup_database() -> tuple[str | None, bool]:
         return None, False
 
 
+def _exclude_next_cache(tarinfo: tarfile.TarInfo) -> tarfile.TarInfo | None:
+    """Filter for tarfile.add — drops .next/cache (webpack build cache, large and unneeded at runtime)."""
+    if "/frontend/.next/cache" in tarinfo.name or tarinfo.name.endswith("/.next/cache"):
+        return None
+    return tarinfo
+
+
 def create_backup_tarball(dump_file: str) -> tuple[str | None, bool]:
     temp_dir = tempfile.mkdtemp()
     tarball = Path(temp_dir) / "huggingpost-backup.tar.gz"
@@ -151,6 +159,11 @@ def create_backup_tarball(dump_file: str) -> tuple[str | None, bool]:
                 tar.add(str(UPLOADS_DIR), arcname="uploads")
             if SECRETS_DIR.exists():
                 tar.add(str(SECRETS_DIR), arcname=".secrets")
+            # Include compiled frontend so subsequent restarts skip the 5-min build.
+            # Exclude .next/cache (webpack cache) — large and not needed to run.
+            if NEXT_DIR.exists() and (NEXT_DIR / "BUILD_ID").exists():
+                tar.add(str(NEXT_DIR), arcname="frontend-next", filter=_exclude_next_cache)
+                logger.debug("Included .next in tarball (webpack cache excluded)")
         size = tarball.stat().st_size
         size_mb = size / 1024 / 1024
         logger.debug(f"Tarball created ({size_mb:.2f} MB)")
@@ -306,6 +319,18 @@ def download_and_restore() -> bool | None:
                 except Exception as e:
                     logger.warning(f"Failed to restore upload {item.name}: {e}")
 
+        # Restore compiled Next.js frontend (.next without cache).
+        # If present, start.sh will skip the 5-min `pnpm run build:frontend`.
+        next_src = Path(temp_dir) / "frontend-next"
+        if next_src.exists():
+            try:
+                if NEXT_DIR.exists():
+                    shutil.rmtree(NEXT_DIR)
+                shutil.copytree(next_src, NEXT_DIR)
+                logger.info(f"Restored .next from backup ({sum(f.stat().st_size for f in NEXT_DIR.rglob('*') if f.is_file()) / 1024 / 1024:.1f} MB)")
+            except Exception as e:
+                logger.warning(f"Failed to restore .next (will rebuild on start): {e}")
+
         return restore_database(str(sql))
     except Exception as e:
         logger.error(f"Restore from HF failed: {e}")

start.sh

@@ -157,6 +157,34 @@ else
     echo "   Add HF_TOKEN as a Space secret to enable DB+uploads backup."
 fi
 
+# ── Build Next.js frontend (first boot or after a fresh deploy) ───────────────
+# next build is NOT run during docker build — the HF builder's ~4 GB cgroup
+# limit is less than what next build needs. We run it here where the runtime
+# has 16 GB. On subsequent starts the .next directory is restored from the
+# HF Dataset backup, so this block only executes once (or after a version bump).
+FRONTEND_NEXT="${POSTIZ_DIR}/apps/frontend/.next"
+if [ ! -f "${FRONTEND_NEXT}/BUILD_ID" ]; then
+    echo ""
+    echo "  ┌─────────────────────────────────────────────────────────────────┐"
+    echo "  │  Building Next.js frontend (first boot — takes ~5 min)          │"
+    echo "  │  Dashboard is live at ${PUBLIC_URL}/                             │"
+    echo "  │  Postiz will start automatically when the build finishes.        │"
+    echo "  └─────────────────────────────────────────────────────────────────┘"
+    echo ""
+    cd "${POSTIZ_DIR}"
+    SENTRY_DSN="" \
+    SENTRY_AUTH_TOKEN="" \
+    SENTRY_ORG="" \
+    SENTRY_PROJECT="" \
+    NEXT_PUBLIC_SENTRY_DSN="" \
+    NEXT_TELEMETRY_DISABLED=1 \
+    NEXT_PRIVATE_SKIP_SIZE_MINIMIZATION=true \
+    NODE_OPTIONS="--max-old-space-size=8192" \
+    pnpm run build:frontend 2>&1 | sed 's/^/[frontend-build] /'
+    echo "Frontend build complete."
+    cd /
+fi
+
 # ── Cloudflare proxy bootstrap ───────────────────────────────────────────────
 if [ -n "${CLOUDFLARE_WORKERS_TOKEN:-}" ]; then
     echo "Setting up Cloudflare proxy..."