Getting started

Three steps: run vdoc, publish a version, open it.

Run it

uv

Runs vdoc straight from PyPI, installing nothing permanently.

VDOC_API_USERNAME=me VDOC_API_PASSWORD=change-me uvx vdoc run

pip

Installs vdoc into the active environment, then starts it.

pip install vdoc && VDOC_API_USERNAME=me VDOC_API_PASSWORD=change-me vdoc run

Docker

Mounts directories for the uploads and the database, so they outlive the container.

docker run -p 8080:8080 -e VDOC_API_USERNAME=me -e VDOC_API_PASSWORD=change-me -v ./vdoc-docs:/srv/vdoc/docs/ -v ./vdoc-data:/srv/vdoc/data/ voraus.jfrog.io/docker/vdoc:0.31.2

🚀 vdoc is now available

It answers on localhost:8080 with an empty landing page. The credentials set above are what uploads and the admin pages ask for. vdoc refuses both while the credentials are still the defaults admin/admin, because those are published here. Configuration covers the rest of the settings.

Publish a version

Take any directory with an index.html in it, zip it up and post it:

cd path/to/built/docs
zip -r ../docs.zip .
curl --user me:change-me \
  --form "file=@../docs.zip;type=application/zip" \
  http://localhost:8080/api/projects/example/versions/1.0.0

The archive is unpacked as version 1.0.0 of a project called example. Publishing documentation has the rules an upload has to satisfy and how to wire this into a pipeline.

Open it

• http://localhost:8080/example/1.0.0/ — the version you just published
• http://localhost:8080/example/latest/ — whichever version is newest

Upload a 1.1.0 next and the version picker in the header has two entries, with latest following the newer one.

Then what

An instance that serves more than one project usually wants a name, a logo and some grouping. Configuration covers vdoc's own settings and the admin page, which sets the display name, description, category and visibility of each project. Plugins covers how the instance presents itself.