Deployment

Orveth services are ordinary Node.js processes. This guide covers running your API in production and hosting the static documentation site from this repository.

Deploying an Orveth HTTP service

Build your TypeScript project to JavaScript (or run with a TypeScript loader in development), set environment variables, and start a single Node process that calls app.listen(port) or binds an external http.Server via app.toRequestListener().

Process model

• One listener per process is the common pattern. Scale horizontally behind a load balancer when you need more throughput.
• Use registerPrismaShutdown from @orveth/prisma so SIGTERM/SIGINT disconnect Prisma Client before exit.
• Terminate TLS at Node with @orveth/https, or place nginx, Caddy, or a cloud load balancer in front and run plain HTTP internally.

Health checks

Expose a lightweight route (for example GET /health) that returns ctx.ok(...). For database readiness, mount createDatabaseHealthRoute on a separate path such as /health/db.

Container sketch

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
COPY package.json .
EXPOSE 3000
CMD ["node", "dist/main.js"]

Environment variables

Parse configuration at startup with @orveth/config so missing secrets fail fast before the server accepts traffic. Never commit secrets; inject them from your host or secret manager.

Hosting this documentation site

The docs app lives at apps/docs. It is a Next.js project with output: "export", so next build writes static HTML to apps/docs/out.

Vercel

GitHub Pages

The workflow at .github/workflows/docs-pages.yml builds with ORVETH_PAGES_BASE_PATH=/{repository-name} so assets resolve under https://<owner>.github.io/<repo>/.

1. Repository Settings → Pages → Source: GitHub Actions.
2. Push to main or run the workflow manually. The deploy job publishes apps/docs/out.
3. If deploy fails while build succeeds, check Environments → github-pages allows deployments from your default branch.

Local static preview

pnpm --filter @orveth/docs build
npx serve apps/docs/out

Monorepo note

The documentation site does not import workspace packages at build time today. If you add live code samples that import @orveth/*, declare those dependencies in apps/docs/package.json and build packages before the docs build step on CI.

Source repository

https://github.com/orvethjs/orveth