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.

The main local ports are 9200 for the website and dashboard, 9201 for the API, 9202 for the hosted-site frontloader, 9203 for Postgres, and 9204 for the MinIO S3 endpoint.

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 the dashboard at /dash for tenant configuration and editorial workflows, the API on port 9201 for programmatic access, and the frontloader on port 9202 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.