---
title: Deployment
description: Build the site, run it in a container, and serve it at hexelstudio.com/docs.
url: https://hexelstudio.com/docs/reference/deployment
---

## Build

```bash
ppnpm install --frozen-lockfile
pnpm build
```

Every page, the search index, `llms.txt` and the Markdown copies are generated during the build. So is the API reference: a build reads each spec's `source`, so a spec whose source is a `~/` path, or a URL the build cannot reach, needs a committed `cache` to build on Vercel, in CI or in Docker. See [API reference generation](https://hexelstudio.com/docs/reference/api-reference#keep-a-local-copy). `next.config.ts` sets `output: "standalone"`, so `.next/standalone` holds a minimal server.

## Container

The `Dockerfile` has the same shape as the homepage image: Node 24, a non-root user, and a health check. The health check calls `/docs`, because every route lives there.

```bash
docker build -t hexel-docs .
docker run --rm -p 3000:3000 hexel-docs
```

## Serving at hexelstudio.com/docs

The site sets `basePath: "/docs"`, so its pages **and** its scripts and styles are all under `/docs`. That lets the homepage send one path prefix to this app without clashing with its own `/_next` files.

Today the homepage sends `/docs` to Mintlify. Point the same rewrite at this app instead:

```ts homepage/next.config.ts {5}
async rewrites() {
  return [
    {
      source: "/docs/:path*",
      destination: `${process.env.DOCS_ORIGIN}/docs/:path*`,
    },
  ]
},
```

`:path*` also matches `/docs` itself, so the landing page, every page, `search.json`, `llms.txt`, the `.md` copies and all assets go through this one rule.

<Warning>
  Links from the homepage into the docs must be plain `<a>` tags, not `next/link`. Each app can only navigate client-side within itself.
</Warning>

## Before switching over

<Steps>
  <Step title="Move the pages">
    Copy the Mintlify `.mdx` files into `content/docs`, keeping their paths, and paste the `navigation.tabs` block from `docs.json` into `docs.config.ts`.
  </Step>
  <Step title="Build">
    `pnpm build` names any listed page without a file and any component the site does not provide.
  </Step>
  <Step title="Compare">
    Open each page next to its Mintlify version. Links that start with `/docs` keep working, since the URLs are the same.
  </Step>
</Steps>