Publishing the Docs Site

The docs system now has two layers:

• apps/docs-site/public/content/ is the source of truth for the markdown content.
• apps/docs-site/scripts/ owns the generator, Mermaid export, and explorer graph data.
• apps/docs-site/ is the deployable frontend that packages those assets behind a proper app shell built with @crown/router and @crown/ui.

The public docs image builds the latest generated docs directly inside the frontend app and serves the compiled site with nginx.

What the image serves

The public docs image serves:

• / as the app-style docs frontend
• /explorer/ as the interactive architecture explorer
• /diagrams/generated/* for the generated Mermaid, SVG, and PNG artifacts
• /content/* for the raw markdown source pages shipped from apps/docs-site/public/content/

That means the polished frontend and the raw underlying artifacts ship together in one image.

Source locations

Use:

• apps/docs-site/ for the frontend shell, routing, content, and generator scripts
• docker/Dockerfile.docs for the production image build
• apps/docs-site/public/diagrams/generated/ for generated Mermaid, SVG, and PNG outputs

Local workflow

Generate the latest content/data artifacts and build the frontend app locally:

cd apps/docs-site
bun run build

Refresh Mermaid SVG/PNG diagram artifacts explicitly when diagram sources change:

cd apps/docs-site
bun run generate

For local app development with the new UI:

cd apps/docs-site
bun run dev

For a production-style local preview, use:

cd apps/docs-site
bun run preview

Building the image

Build the deployable docs image from the repo root:

docker build -f docker/Dockerfile.docs -t crown-docs .

The Docker build now does the important bits itself:

1. installs workspace dependencies
2. regenerates the docs artifacts inside apps/docs-site
3. builds apps/docs-site
4. copies the compiled frontend into nginx

To run the image locally:

docker run --rm -p 4000:80 crown-docs

Then open:

• http://localhost:4000/ for the docs frontend
• http://localhost:4000/explorer/ for the interactive explorer

Deploying with Coolify

If you want to publish the docs through Coolify, point the application at:

• the repo root as build context
• docker/Dockerfile.docs as the Dockerfile

Recommended runtime settings:

• expose port 80
• place it behind a domain such as docs.<your-domain>
• keep the deployment image registry-backed, just like the other frontend apps

Suggested CI sequence

For public docs deploys, the sequence should usually be:

1. bun run --cwd apps/docs-site generate
2. bun run --cwd apps/docs-site generate:check
3. bun run --cwd apps/docs-site build
4. build the docs image
5. push the image to the target registry
6. let Coolify deploy the updated image

That keeps the published site deterministic, verifies the generated assets are current, and ensures the app shell matches the latest docs state.

When to rebuild

Rebuild the docs image whenever you change:

• architecture markdown pages
• generated diagram scripts or outputs
• explorer code or graph data
• docs app routes, styling, or shell layout
• deployment references or operating guides