# Deploy a Docusaurus docs site to your own VPS

Deploy a Docusaurus documentation site to your own VPS: ox runs the build from package.json and Caddy serves the build folder over HTTPS, no ox.toml.

To deploy a Docusaurus site to a VPS with ox, add the repo as a project and deploy it, with no Dockerfile and no ox.toml. ox reads `docusaurus.config.js` and `package.json`, runs `npm install` and `npm run build`, and Caddy serves `build` over HTTPS with no app process. Run `ox check` in your repo to see the same plan before the first deploy.

**Plan verified, real-server test pending.** The plan below is what `ox check` prints for a minimal Docusaurus repo in ox's tests. A deploy on a real server is not recorded yet.

ox reads `docusaurus.config.js` and `package.json`, builds the plan on the card, and serves `build` as files on your server.

## What ox detects in a Docusaurus repo

This is the plan `ox check` prints for a minimal a Docusaurus documentation site, with no ox.toml. Each row says where its value came from: a file in the repo, or ox's default.

| Field | Value | Source |
| --- | --- | --- |
| `static.dir` | `build` | `detected:docusaurus.config.js` |
| `build.install` | `npm install` | `detected:package.json` |
| `build.commands[0]` | `npm run build` | `detected:package.json` |
| `tools.node` | `24` | `default` |

## The ox.toml for Docusaurus

None is needed: the plan above comes from the repo alone. Write one to serve your own domain or to change what ox detected. This one passes `ox check` against the same repo: `[static]` needs its `dir`, and the build stays detected.

ox.toml, optional:

```toml
domains = ["docs.example.com"]

[static]
dir = "build"
```

## Check and deploy Docusaurus

Add the repo as a project, then check and ship it from a terminal:

Check, deploy and read the logs:

```sh
ox check                                # in the repo: the plan above, offline
ox new <owner/repo> --server <server>  # add the repo as a project
ox deploy <project> --wait              # stream the deploy, exit with its result
ox runs <project>                      # past deploys, with their ids
ox logs <project> --run <id>         # one deploy's log
```

A static site has no app process, so its log is the deploy's own: `ox runs` lists them and `--run` reads one.

## Variables to set for Docusaurus

None before the first deploy: `ox check` asks for no variable. Add your own on the dashboard's Variables tab or with `ox vars set <project> KEY`.

ox provides these to the app itself: `PORT`, `HOST`, `OX_ENV`, `OX_PROJECT`, `OX_RELEASE`, `OX_DATA_DIR`, `PUBLIC_URL` and `PUBLIC_HOST`.

## If the Docusaurus deploy fails

- `build 1/1: npm run build: exit status 1`: Your build failed. The lines above it are the build's own output; run the same command on your computer, fix it, and push. [More](https://deploywithox.com/docs/troubleshooting#build-failed).
- `the build left no dist directory`: The build wrote its files somewhere else. Set `[static] dir` to the folder your build makes. [More](https://deploywithox.com/docs/config#static).
- `killed by the out-of-memory killer (the build needs more memory than the project or host allows)`: The build ran out of memory. Raise the project's memory, add swap, or use a bigger server. [More](https://deploywithox.com/docs/troubleshooting#out-of-memory).

Your visitors never see a failed deploy: the previous release keeps serving until the new one passes its health check.

## Next steps

- [The static site guide](https://deploywithox.com/docs/guides/static-site): Vite, Astro and plain HTML with a full ox.toml.
- [The `[static]` keys](https://deploywithox.com/docs/config#static): the folder Caddy serves, single-page mode and an API beside it.
- [Add a custom domain](https://deploywithox.com/docs/operate/domains) with one A record; Caddy gets the HTTPS certificate.
- [Roll back](https://deploywithox.com/docs/operate/rollback) to an earlier release without a rebuild.

## Docusaurus FAQ

### Do I need a Dockerfile or an ox.toml to deploy a Docusaurus site to a VPS?

No. ox does not use Docker, and `ox check` on a Docusaurus repo with no ox.toml prints `Ready to deploy.` Write an ox.toml only to change what ox detected.

### What does ox install on the server for Docusaurus?

Only what the plan names: `node 24` (ox's default). Your app's own dependencies are installed by the build into the release folder, not system-wide.

### Does Docusaurus search work on my own server?

Docusaurus builds plain files, and Caddy serves them as they are. Search that runs in the browser works the same; a hosted search service needs its keys in your build variables.

## Related guides

- [**Astro**Deploy an Astro static site to your own VPS: ox reads astro.config.mjs, runs astro build, and Caddy serves dist over HTTPS with no app process running.](https://deploywithox.com/docs/guides/astro)
- [**Astro SSR**Deploy an Astro app with the @astrojs/node adapter to your own VPS: ox builds it, runs dist/server/entry.mjs under systemd, with Caddy and HTTPS in front.](https://deploywithox.com/docs/guides/astro-ssr)

Every stack ox deploys, and the ones it does not yet, is on the [Stacks page](https://deploywithox.com/docs/guides).

Last updated 2026-10-09. The page as HTML: https://deploywithox.com/docs/guides/docusaurus