From 6f6336bc18e174398fa6ebf8eb964a71c62a092a Mon Sep 17 00:00:00 2001
From: Kyle Tse <hi@kylet.se>
Date: Fri, 26 Jun 2026 00:30:33 +0100
Subject: [PATCH] build(docs): deploy VitePress docs via platform Dockerfile
 (Bun -> Caddy)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The committed sylphx.toml used `strategy = "auto"`, which cannot build flow's
docs as a static site: flow is a Bun *workspace* monorepo with a turbo.json, so
the platform's auto buildpack routes it to a node-server build, and the
static-frontend detector additionally requires an index.html at the source root
(VitePress is markdown, the dist is produced only after build). The result would
build the monorepo via turbo and try to run a non-existent node server.

Match how every first-party Sylphx app deploys (httphole, sylphx-ai,
alpha-foundry all use `strategy = "dockerfile"`): add an explicit Dockerfile
that mirrors the platform's canonical bun-static buildpack template — Bun builds
the VitePress site, Caddy serves the static output on :3000 — and switch
sylphx.toml to the dockerfile strategy with a web service + health path.

Verified locally: `docker build` succeeds, the container returns HTTP 200 with
real VitePress content at `/`, `/guide/getting-started`, and the `.html` route.

Enables the single-source docs deploy on the Sylphx Platform; the duplicate
vercel.json is removed separately once the platform deploy is verified live
(#165).
---
 Dockerfile  | 42 ++++++++++++++++++++++++++++++++++++++++++
 sylphx.toml | 23 ++++++++++++++++++-----
 2 files changed, 60 insertions(+), 5 deletions(-)
 create mode 100644 Dockerfile

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 00000000..79a39870
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,42 @@
+# syntax=docker/dockerfile:1.7@sha256:a57df69d0ea827fb7266491f2813635de6f17269be881f696fbfdf2d83dda33e
+# flow docs — VitePress static site built with Bun, served by Caddy.
+#
+# Mirrors the Sylphx Platform canonical `bun-static` buildpack template
+# (ADR-071 v2: package.json frontend build -> Caddy). flow is a Bun *workspace*
+# monorepo with a turbo.json, so the platform's `auto` buildpack routes it to a
+# node-server build instead of the static path — the docs site therefore
+# declares an explicit Dockerfile, the same escape hatch every first-party
+# Sylphx app uses. Base images are digest-pinned to match the platform's
+# base-images.json.
+
+ARG SOURCE_DATE_EPOCH
+
+FROM oven/bun:1.3-alpine@sha256:4de475389889577f346c636f956b42a5c31501b654664e9ae5726f94d7bb5349 AS builder
+WORKDIR /app
+# VitePress and its bundler live in devDependencies; keep the build stage in
+# development mode so they install.
+ENV NODE_ENV=development
+# Bun reconciles the frozen lockfile against every workspace manifest, so copy
+# the whole tree before install rather than just the root package.json.
+COPY . ./
+RUN --mount=type=cache,id=bun-flow-docs,target=/root/.bun/install/cache,sharing=locked \
+    bun install --frozen-lockfile
+RUN bun run docs:build
+
+FROM builder AS probe
+WORKDIR /app
+# L3 static-output probe — the build must produce a document Caddy can serve.
+RUN test -f docs/.vitepress/dist/index.html
+
+FROM caddy:2-alpine@sha256:834468128c7696cec0ceea6172f7d692daf645ae51983ca76e39da54a97c570d AS runner
+WORKDIR /srv
+ARG SOURCE_DATE_EPOCH
+# VitePress is a static MPA: resolve clean URLs to their `.html` file and
+# directory indexes, falling back to index.html for client-routed deep links.
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup \
+ && chown -R appuser:appgroup /srv \
+ && printf ':3000 {\n  root * /srv\n  encode gzip\n  try_files {path} {path}.html {path}/ /index.html\n  file_server\n}\n' > /etc/caddy/Caddyfile
+COPY --from=probe --chown=appuser:appgroup /app/docs/.vitepress/dist /srv
+USER appuser
+EXPOSE 3000
+CMD ["caddy", "run", "--config", "/etc/caddy/Caddyfile", "--adapter", "caddyfile"]
diff --git a/sylphx.toml b/sylphx.toml
index c2d72bae..c26f09a2 100644
--- a/sylphx.toml
+++ b/sylphx.toml
@@ -1,16 +1,29 @@
 version = "1"
 
 [project]
-name = "@sylphx/flow-monorepo"
+name = "Sylphx Flow"
 slug = "flow"
 org = "sylphx"
+default_env = "production"
+description = "Sylphx Flow documentation site (VitePress) — dogfoods the Sylphx Platform as the single source of truth for the docs deploy."
 
 [build]
-strategy = "auto"
-context = "docs"
+strategy = "dockerfile"
+dockerfile = "Dockerfile"
+context = "."
 
 [[services]]
 name = "web"
 type = "web"
-port = 80
-watch_paths = ["docs/**"]
+port = 3000
+watch_paths = [
+  "docs/**",
+  "package.json",
+  "bun.lock",
+  "Dockerfile",
+  "sylphx.toml",
+]
+
+[services.health]
+mode = "http"
+path = "/"