Docsy supports public static hosting and a standalone server running on Node or Bun. Use Node 22.22 or newer to develop and build. Bun 1.3.5 or newer is an optional production runtime. Choose open mode with agent.query: false for public static documentation; locked mode or agent.query: true uses the server build.

Deploy an open static build

Configure open mode and the public URL:

Code example
site:
  origin: https://docs.example.com
  basePath: /

access:
  mode: open
agent:
  query: false

Build the project:

Code example
npm ci
npm run build

Astro writes the static site to dist/. Docsy also stages a host-neutral copy under release/, including the mount-path directory when site.basePath is not /.

Upload dist/ when the hosting platform already mounts the project at the configured base path, as GitHub Pages does. Upload release/ when the server expects the mount-path directory to exist inside the document root.

Run locked mode

Locked mode needs the standalone server. Public sites can also use this runtime by setting agent.query: true to enable live JSON retrieval:

Code example
access:
  mode: locked
  provider:
    type: header
    tierHeader: x-docsy-tiers
    userHeader: x-docsy-user

Build and start it:

Code example
npm ci
npm run build
HOST=0.0.0.0 PORT=8080 npm run preview

Put the process behind the trusted authentication proxy described in the lock-mode guide. Do not expose a header-provider deployment directly to the internet.

Run the production build on Bun

Install and build with Node as above, then choose Bun for the production process:

Code example
HOST=0.0.0.0 PORT=8080 npm run start:bun
# Or: HOST=0.0.0.0 PORT=8080 bun scripts/start.mjs

No YAML runtime switch is required. access.mode and agent.query still select static versus server output; the command selects the runtime. start:bun also serves staged static output, so public sites can use the same entry point.

This is production-runtime support tested with Bun 1.3.5. Node remains required for the documented installation, generation, validation, and build commands. It does not imply that Bun’s package manager, build toolchain, or test runner replaces those tools. The npm run test:runtime:bun integration check starts real Bun processes against generated static and server builds and checks page, Markdown, search, version/locale, permission-gate, and JSON query behavior.

For a Bun runtime container:

Code example
docker build -f Dockerfile.bun -t docsy-bun .
docker run --rm -p 8080:8080 docsy-bun

Dockerfile.bun builds on Node and runs on a pinned Bun image. The default Dockerfile and Compose service remain Node-based.

Use Docker Compose

The repository includes a multi-stage Dockerfile and Compose service:

Code example
docker compose up --build

The container builds the configured site and starts the correct production shape. It works for the static preview server and for the standalone locked-mode server.

Supply environment-specific configuration

Use environment placeholders for values that change by deployment:

Code example
site:
  origin: ${DOCSY_ORIGIN:-http://localhost:4321}

Select a completely different YAML file with DOCSY_CONFIG:

Code example
DOCSY_CONFIG=docsy.enterprise.yaml npm run build

Rebuild after changing configuration, Markdown, OpenAPI, or SDK sources. These inputs are compiled into the output.

Health and exposure checklist

  • npm run validate and npm run build succeed in CI.
  • site.origin and site.basePath match the public URL.
  • Only public/ assets are directly exposed as static source files.
  • Protected inputs remain outside public/.
  • Locked mode cannot be reached around the trusted proxy.
  • The proxy removes visitor-supplied identity headers before setting its own.
  • Search results and Markdown exports are tested for both authorized and unauthorized visitors.