Docs

📚 A self-hosted, OIDC-protected documentation and WebDAV publishing service.

Docs serves generated documentation from persistent storage and supports both browser publishing and automated uploads. The image is built with xcaddy and includes caddy-webdav and caddy-oidc, plus an isolated JWT authorizer for machine-to-machine publishing.

Generated sites such as mdBooks keep their original HTML, CSS, JavaScript, and image paths after upload. The complete application documentation is available as an mdBook under docs/.

Highlights

• OIDC login with any compatible identity provider
• Public documentation under /public/*
• WebDAV publishing for PUT, DELETE, MKCOL, MOVE, and COPY
• Machine writes restricted to a configurable API permission
• Persistent storage for generated mdBooks and other static sites

How it works

Expose the service at an HTTPS hostname of your choice, for example https://docs.example.com. Files are stored below /srv/docs and are addressed by their path:

• /public/... serves public files from /srv/docs/public/... without login.
• Every other GET or HEAD request requires an interactive OIDC session.
• PUT, DELETE, MKCOL, MOVE, and COPY are WebDAV publishing operations. They require the configured API permission in a machine-to-machine bearer token.

Home page

The root URL / serves /srv/docs/index.html. If no index file exists, Docs serves a directory listing instead.

Quick Start

Docs is a regular containerized application and can run with Docker, Podman, Kubernetes, or another container runtime. Mount a persistent writable directory at /srv/docs, publish the HTTP port 8080, and provide the required environment variables and secrets.

Example Docker invocation:

docker run --name docs \
  --publish 8080:8080 \
  --volume "$PWD/data:/srv/docs" \
  --env-file docs.env \
  registry.example.com/owner/docs:v0.0.1

Terminate TLS at a reverse proxy or ingress and forward HTTP traffic to port 8080. The image also starts the internal machine-token authorizer on port 9090; it is used internally and should not be published.

For local validation:

docker build .

The runtime needs a writable /srv/docs directory. Use a persistent volume or host directory so uploaded files survive container replacement.

Identity provider

Docs requires an OAuth2/OIDC-compatible identity provider for protected reads and human publishing. Pocket ID is the recommended provider because it is lightweight, supports passkeys, groups, and API permissions, and has been tested with this application. Other standards-compliant providers such as Authentik or Keycloak can be used as well.

Create a confidential OIDC client with:

https://docs.example.com/oauth2/callback

Request the scopes required by your provider for identity and profile claims. OIDC users can read documentation, but cannot publish or modify files.

For machine-to-machine publishing, configure an API/resource with this audience:

https://docs.example.com

Grant the machine client the configured publishing permission (for example docs:publish) and request it with the client-credentials flow. Machine tokens are checked independently for signature, issuer, audience, expiry, and permission; they do not need a user group claim.

Configuration

Set these non-secret settings in the container environment:

OIDC_ISSUER=https://id.example.com
OIDC_AUDIENCE=https://docs.example.com
OIDC_CLIENT_ID=<oidc-client-id>
OIDC_PUBLISH_SCOPE=docs:publish
DOCS_BASE_HOST=docs.example.com

Set these secret values in the container environment or a secret manager:

OIDC_CLIENT_SECRET=<oidc-client-secret>
OIDC_COOKIE_SECRET=<random-32-or-64-byte-secret>

Do not place either secret in this repository or in the container image. The machine client must request the configured publishing permission for the audience https://docs.example.com when using client credentials.

Images

Forgejo Actions publishes images to the repository registry:

• :main — current development build from main
• :latest — latest release
• :vX.Y.Z — immutable semantic-version release tag

Release builds include OCI source, version, revision, and creation-date labels.

Choose the deployment and secret-management method that fits your environment.

Documentation site

The application documentation is maintained in docs/ as an mdBook. The Forgejo workflow builds it with mdBook and publishes the generated book/ directory to the configured WebDAV path on pushes to main. Pull requests build the book but do not publish it.

The Delete published documentation workflow can be started manually to remove the published /docs/ tree. It requires entering DELETE explicitly and does not affect the source files in this repository.

Contributing

Forgejo Actions validates pull requests and Renovate manages dependency updates.