Deployment

A folder is the
whole deployment

From a single static directory to a hardened Docker stack with an AI gateway — every path, documented end to end.

Static hosting

OpenDoc UI compiles to a single self-contained directory. Build once, copy dist/ anywhere, and the entire application works without a server process, database or runtime dependency.

npm ci npm run build # dist/ with index.html, index.js, 404.html

Deploy dist/ to nginx, Netlify, Vercel, Cloudflare Pages, S3 static websites or Apache. The included 404.html provides SPA fallback so deep links keep working on hosts without rewrite rules — and because routing is hash-based, even hosts with no fallback support work.

GitHub Pages

The repository ships a ready-made Pages workflow: on every push it installs dependencies, copies the demo configuration, builds with the correct base path and deploys — the live demo is always current with the latest commit.

# .github/workflows/pages.yml — highlights env: VITE_BASE_PATH: /${{ github.event.repository.name }}/ VITE_LOAD_FROM_URL: 'true' steps: - run: npm ci - run: cp public/demo/config.pages.json public/config.json - run: npm run build

Project sites get the /<repository>/ base path automatically; custom domains keep the root. Deep links and local file loading work unchanged under the subpath because the application routes through the URL hash.

Docker

Docker with the Compose plugin is the only prerequisite. The image uses a lockfile-pinned npm ci builder and serves the verified bundle from nginx with a working health check.

docker compose up --build --detach # open http://localhost:3000 — stop with: docker compose down

docker/config.json is mounted read-only and controls which specifications the deployment presents — edit it and reload; no image rebuild needed. Port, image name, container name and restart policy are environment-driven (OPENDOC_PORT, OPENDOC_IMAGE_NAME, OPENDOC_CONTAINER_NAME, OPENDOC_RESTART_POLICY), with helper scripts for Windows, macOS and Linux.

Builder CLI — npm run make

A guided, interactive builder that asks what your deployment should include — specification sources, URL loading, base path, AI options — and produces a ready-to-ship dist/ with the matching configuration baked in.

Configuration modes

  • Mode 1 — public/config.json: a pre-defined catalog of specifications served alongside the app.
  • Mode 2 — window.INITIAL_CONFIG: the same catalog injected at page level, useful when embedding.
  • Hybrid: configured specs and local file opening together.
  • Mode 3 — no configuration: pure local mode; users open files from disk with persistent history.

Optional AI gateway

For teams that want provider keys server-side, the included hardened gateway (server/ai-gateway.ts) enforces token authentication, origin allowlists, rate limits, concurrency bounds and upstream timeouts. Reference implementations exist for nine frameworks — Express, FastAPI, Django, Laravel, Rails, Spring Boot, ASP.NET Core, Gin and Axum — so it drops into whatever you already run.