Why The Docs Live With The API Image

One of the useful architectural choices in this repository is that the docs are published with the application image instead of being treated as a separate service.

tip

That keeps the public guide version aligned with the code and deployment that operators are actually running.

The deployment model is simple:

• Docusaurus builds static assets during the Docker build
• the built site is copied into the runtime image
• FastAPI serves those files under /guide

That has a few practical consequences for this project:

• the docs update when the image updates
• there is no extra router or TLS surface to maintain
• local and swarm deployments keep the same documentation path
• operational notes can describe the exact runtime files and URLs that the service exposes

For FastAPI-mapserver, that is the right tradeoff. This stack already has enough moving parts with MapServer, MapCache, Celery, Redis, terrain outputs, and HySpex jobs. Splitting documentation into a separately deployed site would add another versioning problem without solving an urgent one.