Postpiece Docs and Local Setup Guide

Postpiece documentation

Postpiece splits the marketing site, control plane, API, and hosted-site renderer into separate local apps so you can test the whole publishing stack without production credentials.

Local development

Start Docker dependencies with docker compose up -d postgres minio minio-init, then start the application processes with taskmux start.

Taskmux serves the apps under wildcard hostnames: https://postpiece.localhost (website + dashboard), https://api.postpiece.localhost (API), https://*.postpiece.localhost (hosted-site frontloader), https://mcp.postpiece.localhost (MCP). Set POSTPIECE_BASE_HOST in your worktree's .envrc to vary the suffix. Postgres runs on 127.0.0.1:9203 and MinIO on 127.0.0.1:9204.

Application layout

apps/website serves postpiece.com and the /dash control plane. apps/api serves the Hono Worker API. apps/sites serves hosted tenant sites and public media responses.

Local media uploads use MinIO as the S3-compatible target so production R2 credentials can stay in ignored env files.

Implementation notes

In TanStack Start route modules, keep database and other server-only imports inside server functions and loaders so the browser graph does not pull in Node-only modules.

In browser-reachable modules, prefer narrow @postpiece/core subpaths instead of the barrel export to avoid bundling server-only code into the client build.

Operational workflow

Use /dash on the dashboard host for tenant configuration and editorial workflows, api.<base-host> for programmatic access, and a tenant subdomain on <site>.<base-host> to verify hosted public rendering.

When reviewing regressions, verify the route boundary first. A dashboard issue in apps/website usually needs different debugging than a public runtime issue in apps/sites or an upload path issue in apps/api.