DOCAT

DOCAT is a lightweight, self‑hosted service that provides version‑aware static documentation hosting. It sits as a thin HTTP layer in front of pre‑generated MkDocs, Sphinx, or MDBook builds and exposes a RESTful API for managing projects, versions, and access tokens. The core idea is to keep the server minimal—no rendering or build logic—while offering a clean, authenticated interface for pushing new documentation artifacts.

Architecture

DOCAT is written in Python 3.11 and uses the FastAPI framework for its web layer, giving it a fast async runtime with automatic OpenAPI documentation. The persistence model is built around an SQLite database (via SQLAlchemy) that stores metadata for projects, versions, and authentication tokens. Static files are served through Nginx which is bundled inside the Docker image; Nginx proxies API calls to FastAPI and serves documentation blobs from a shared volume (/var/docat). This dual‑stack approach allows rapid scaling: the API can be load‑balanced behind a reverse proxy while static assets remain cacheable at the edge.

The project is distributed as a single Docker image (ghcr.io/docat-org/docat), but the codebase is also available on GitHub, making it straightforward to run from source or embed into custom containers. The minimal dependency footprint (FastAPI, Uvicorn, SQLAlchemy) keeps the image small and secure.

Core Capabilities

• Project & Version Management – Create, list, delete projects; upload new versions via a simple PUT /projects/{id}/versions/{ver} endpoint.
• Token‑Based Authorization – Projects can be claimed to receive a JWT‑style token; subsequent mutating requests must supply this token in the Authorization header.
• Static Asset Hosting – Uploaded documentation bundles are extracted to a per‑project directory and served under /doc/{project}/{version}/.
• Metadata API – Endpoints expose project and version metadata (e.g., last update timestamp, size) for integration into CI pipelines.
• Webhooks & Callbacks – While not yet fully featured, the API design leaves room for future webhook support to trigger downstream processes (e.g., CDN cache purges).

Deployment & Infrastructure

DOCAT is intentionally container‑centric: the Dockerfile pulls a lightweight Python base image, installs dependencies, and copies Nginx config. The only required volume is /var/docat, which persists both the SQLite database and all static files. For production, the image can be run behind a corporate reverse proxy with TLS termination and HTTP basic auth for write operations. Because Nginx serves static files, scaling horizontally is trivial—multiple instances can share a networked filesystem or an object store (S3, MinIO) mounted to /var/docat.

Integration & Extensibility

The REST API is fully documented via OpenAPI, allowing developers to generate client libraries in any language. The CLI tool docatl demonstrates how to consume the API, but direct curl calls are equally straightforward. While DOCAT currently focuses on hosting, its plugin architecture (planned) will enable extensions such as custom authentication backends, analytics dashboards, or integration with CI/CD tools. The public documentation and GitHub issue tracker foster community contributions to these areas.

Developer Experience

• Clear Configuration – All runtime settings are exposed as environment variables (DOCAT_DB_PATH, DOCAT_ROOT, etc.), making it easy to tweak in Docker Compose or Kubernetes.
• Comprehensive Docs – The repository contains a doc/ folder with step‑by‑step guides, API references, and usage examples.
• Active Community – Gitter chat support and an open issue tracker provide quick help for integration questions.
• Licensing – The MIT license allows unrestricted use, modification, and redistribution—ideal for internal tooling.

Use Cases

1. Internal API Documentation – Teams can host multiple versions of their public APIs, ensuring legacy docs remain accessible.
2. Open‑Source Projects – Release notes and docs for each tag can be pushed automatically from CI pipelines.
3. Education & Training – Courses that evolve over semesters can maintain versioned handouts and slides.
4. Compliance & Auditing – Storing static docs in a versioned, authenticated repository satisfies audit requirements.

Advantages

• Simplicity – No build step; DOCAT only serves files, reducing attack surface.
• Speed – Fast API + Nginx combination yields sub‑50 ms latency for static asset requests.
• Flexibility – Works with any static generator; developers control the build process separately.
• Self‑Hosted Control – Full ownership of data and access policies, crucial for regulated environments.
• Low Resource Footprint – The container runs on modest hardware (512 MiB RAM, 1 CPU) and scales horizontally with minimal effort.

In short, DOCAT gives developers a lean, self‑hosted platform to expose multiple versions of static documentation with robust API controls and minimal operational overhead.