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.

Use a {/* truncate */} comment to limit blog post size in the list view.

The most important work was around the API surface that operators and workflows actually hit.

On the job side, the test suite now covers more of the behavior that tends to regress quietly:

• listing jobs with refresh behavior for non-terminal states
• status shaping for success, in-progress, failure, and unknown job IDs
• delete and cleanup routes, including tombstone recording and status-based cleanup

Outside the jobs router, coverage was extended to routes that define the operator experience:

• auth endpoints for /token and /login
• config and service-health endpoints
• lightweight dataset listing, duplicate reporting, and missing HySpex variant reporting

This mattered because the runtime story here is bigger than one task queue. The platform depends on consistent behavior across auth, config persistence, dataset state, job manifests, and cache-related routes.

The other major change was CI structure. Instead of keeping everything in one path, the workflow now separates concerns more cleanly:

• unit remains the fast, containerized baseline
• integration stays as its own stage for broader behavior
• smoke now starts the runtime container and validates the health, login, and protected dataset flow independently

The smoke script itself also became less optimistic. It now waits for the health endpoint before trying auth and protected requests, which is the difference between a flaky runner and a useful runtime signal.

Locally, validating that path exposed an environment truth that CI runners usually hide: host ports were already occupied by long-running containers. Once that was understood, the runtime flow was still verified from the live container context, which confirmed that the smoke sequence itself was correct even though the local host bindings were not clean.

The outcome is straightforward: the documentation now explains the system more accurately, and the tests do a better job of protecting the routes and workflows that define how the service is actually used.

The project already had enough moving parts to justify real operational documentation:

• a FastAPI application with a large router surface
• MapServer and MapCache sitting behind the service layer
• Celery and Redis for asynchronous processing
• terrain generation and Mago output handling
• HySpex ingestion paths that can fan out into batch jobs

What changed on day 1 was not just the text. The docs site started to describe the real deployment shape:

• the public host layout under /docs, /ui, /guide, and the OGC endpoints
• storage and manifest behavior under /data
• deployment files and local swarm profiles
• caching, terrain, and HySpex workflows from an operator point of view

That matters because this repository is not a library. It is an operating service, and the documentation has to answer practical questions like:

• where job state is persisted
• how MapCache is regenerated and cleaned
• which manifests define dataset and terrain state
• how public URLs map to runtime services

By the end of the first day, the docs site had stopped looking like a default Docusaurus starter and started reading like the control-plane manual for the stack we actually run.

This project is not just a FastAPI wrapper around a few endpoints. It is the control plane around GeoTIFF datasets, MapServer and MapCache, Celery workers, Redis-backed job state, a built-in frontend, and terrain products that need to stay aligned across API, storage, and deployment.

At a high level, the stack is responsible for four kinds of work:

• ingesting or registering datasets and exposing them through OGC routes
• converting source products into GeoTIFF-backed outputs that the platform can serve consistently
• generating and publishing terrain artifacts for Cesium and related clients
• tracking long-running jobs, especially HySpex CSW parent campaigns that expand into many child jobs

The reason this repository matters operationally is that these features share the same manifests, cache directories, deployment files, and runtime assumptions. A small change in routing, config persistence, or cache generation can affect user-facing map behavior immediately.

That is also why the documentation effort now lives close to the code: operators need one place to understand how /datasets, /jobs, /mapcache, terrain generation, and HySpex-specific flows fit together.

In practice, the platform currently centers on these capabilities:

• GeoTIFF dataset upload, registration, metadata repair, and duplicate detection
• MapServer-backed WMS and related OGC service exposure
• MapCache config generation, cache cleanup, and optional seeding during ingestion
• Celery and Redis orchestration for asynchronous tasks and job introspection
• HySpex CSW ingestion, including resumable parent-batch execution and campaign status tracking
• terrain preparation for Mago and Cesium-oriented clients

Over the last two days, the focus has been tightening this operational surface: turning the docs site into project documentation, replacing scaffold content with real platform notes, expanding route-level test coverage, and separating smoke validation from the main unit path.

This blog is where that work is recorded in smaller, chronological slices.