feat(infra): add MkDocs documentation service

Add containerized MkDocs docs server deployed alongside API/App/Proxy:
- Dockerfile.docs: Python 3.13 + ODBC 18 (same env as API for hook imports)
- docker-compose.yml: docs service on :8002
- Deploy-OpenDateaubase.ps1: SkipDocs flag, service registration, status reporting
- DeployHelpers.psm1: nginx /docs/ routing with WebSocket support for livereload
- EnvironmentProfiles.psm1: DocsPort per environment (8012 staging, 8002 prod)

Exposed via nginx proxy at /docs/ (e.g., http://hostname/docs/).

Author: jeandavidt

Dockerfile.docs

@@ -0,0 +1,48 @@
+# MkDocs documentation site. The build hook (docs/hooks/call_orchestrator.py)
+# imports api.main + scripts/ + schema_dictionary/, so this image needs the same
+# API/ODBC environment as Dockerfile.api — it just runs mkdocs instead of uvicorn.
+FROM python:3.13-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+WORKDIR /app
+
+# OS deps + MSSQL ODBC 18 (same as the API image; the hook imports api.main).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl ca-certificates gcc g++ \
+    unixodbc unixodbc-dev gnupg \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \
+    | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg \
+ && curl -fsSL https://packages.microsoft.com/config/debian/12/prod.list \
+    | tee /etc/apt/sources.list.d/microsoft-prod.list > /dev/null \
+ && apt-get update \
+ && ACCEPT_EULA=Y apt-get install -y --no-install-recommends msodbcsql18 \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN pip install --no-cache-dir uv
+
+# Dependency files first for layer caching
+COPY pyproject.toml uv.lock ./
+COPY src/ ./src/
+COPY importer/pyproject.toml ./importer/pyproject.toml
+
+# --extra api: hook imports api.main. Default dev group pulls mkdocs-swagger-ui-tag.
+RUN uv sync --package open-dateaubase --extra api
+
+# Everything the docs build reads at runtime
+COPY api/ ./api/
+COPY scripts/ ./scripts/
+COPY schema_dictionary/ ./schema_dictionary/
+COPY docs/ ./docs/
+COPY mkdocs.yml ./
+
+ENV PATH="/app/.venv/bin:$PATH"
+
+EXPOSE 8000
+
+# ponytail: dev server (live-reloads doc edits) is fine for an internal docs site.
+# Swap to `mkdocs build` + a static server if the file-watcher's CPU ever matters.
+CMD ["uv", "run", "mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"]

docker-compose.yml

@@ -122,5 +122,15 @@ services:
       - api
     restart: unless-stopped
 
+  docs:
+    build:
+      context: .
+      dockerfile: Dockerfile.docs
+    container_name: open_dateaubase_docs
+    logging: *default-logging
+    ports:
+      - "8002:8000"          # no proxy in compose; docs served directly on :8002
+    restart: unless-stopped
+
 volumes:
   mssql_data:

scripts/deploy/Deploy-OpenDateaubase.ps1

@@ -78,6 +78,9 @@
 .PARAMETER SkipProxy
     Do not deploy/update the nginx proxy service.
 
+.PARAMETER SkipDocs
+    Do not deploy/update the MkDocs documentation service (served at /docs/).
+
 .PARAMETER SkipLogViewer
     Do not deploy/update the OpenObserve log viewer + Vector log shipper services.
 
@@ -150,6 +153,7 @@ param(
     [string]$ApiPort         = '',
     [string]$AppPort         = '',
     [string]$ProxyPort       = '',
+    [string]$DocsPort        = '',
     [string]$LogViewerPort   = '',
 
     [string]$ServiceUser     = 'LocalSystem',
@@ -159,6 +163,7 @@ param(
     [switch]$SkipApp,
     [switch]$SkipImporter,
     [switch]$SkipProxy,
+    [switch]$SkipDocs,
     [switch]$SkipLogViewer,
     [switch]$Uninstall
 )
@@ -193,6 +198,7 @@ if ([string]::IsNullOrWhiteSpace($EnvFile))   { $EnvFile   = Join-Path $InstallD
 if ([string]::IsNullOrWhiteSpace($ApiPort))       { $ApiPort       = $envProfile.ApiPort }
 if ([string]::IsNullOrWhiteSpace($AppPort))       { $AppPort       = $envProfile.AppPort }
 if ([string]::IsNullOrWhiteSpace($ProxyPort))     { $ProxyPort     = $envProfile.ProxyPort }
+if ([string]::IsNullOrWhiteSpace($DocsPort))      { $DocsPort      = $envProfile.DocsPort }
 if ([string]::IsNullOrWhiteSpace($LogViewerPort)) { $LogViewerPort = $envProfile.LogViewerPort }
 
 # The .env file is only required when deploying the API (it carries DB_*).
@@ -214,6 +220,7 @@ if (-not $Uninstall -and -not $SkipImporter) {
 # never collide on a shared host.
 $SVC_API        = "OpenDateaubase-$tag-API"
 $SVC_APP        = "OpenDateaubase-$tag-App"
+$SVC_DOCS       = "OpenDateaubase-$tag-Docs"
 $SVC_PROXY      = "OpenDateaubase-$tag-Proxy"
 $SVC_LOGVIEW    = "OpenDateaubase-$tag-LogViewer"
 $SVC_LOGSHIP    = "OpenDateaubase-$tag-LogShip"
@@ -252,6 +259,7 @@ if ($Uninstall) {
         Remove-NssmService -NssmExe $nssmExe -ServiceName $SVC_LOGSHIP
         Remove-NssmService -NssmExe $nssmExe -ServiceName $SVC_LOGVIEW
         Remove-NssmService -NssmExe $nssmExe -ServiceName $SVC_PROXY
+        Remove-NssmService -NssmExe $nssmExe -ServiceName $SVC_DOCS
         Remove-NssmService -NssmExe $nssmExe -ServiceName $SVC_APP
         Remove-NssmService -NssmExe $nssmExe -ServiceName $SVC_API
     }
@@ -376,6 +384,30 @@ if (-not $SkipApp) {
     Write-Step "Streamlit app started (access via http://localhost:$AppPort once proxy is up)." -Success
 }
 
+# ---------------------------------------------------------------------------
+# Step 8b: Deploy MkDocs documentation service
+# ---------------------------------------------------------------------------
+
+if (-not $SkipDocs) {
+    Write-Step 'Deploying docs service (mkdocs serve)...'
+
+    Install-NssmService `
+        -NssmExe         $nssmExe `
+        -ServiceName     $SVC_DOCS `
+        -Application     $uvExe `
+        -AppParameters   "run mkdocs serve --dev-addr 127.0.0.1:$DocsPort" `
+        -AppDirectory    $InstallDir `
+        -DisplayName     "open_datEAUbase Docs ($tag)" `
+        -Description     "MkDocs documentation site for open_datEAUbase ($Environment; localhost:$DocsPort behind nginx /docs/)" `
+        -StdoutLog       (Join-Path $LogDir 'docs\stdout.log') `
+        -StderrLog       (Join-Path $LogDir 'docs\stderr.log') `
+        -ServiceUser     $ServiceUser `
+        -ServicePassword $ServicePassword
+
+    Start-ManagedService -NssmExe $nssmExe -ServiceName $SVC_DOCS
+    Write-Step "Docs service started (access via http://localhost:$ProxyPort/docs/ once proxy is up)." -Success
+}
+
 # ---------------------------------------------------------------------------
 # Step 9: Register importer Scheduled Task
 # ---------------------------------------------------------------------------
@@ -567,6 +599,7 @@ if (-not $SkipProxy) {
         -AppPort       $AppPort `
         -ProxyPort     $ProxyPort `
         -LogDir        $LogDir `
+        -DocsPort      $(if (-not $SkipDocs) { $DocsPort } else { '' }) `
         -LogViewerPort $(if (-not $SkipLogViewer) { $LogViewerPort } else { '' })
 
     Install-NssmService `
@@ -609,6 +642,10 @@ if (-not $SkipApp) {
     $s = Get-Service $SVC_APP -ErrorAction SilentlyContinue
     $rows += [pscustomobject]@{ Component='App';      Type='Windows Service';     Name=$SVC_APP;     Status=${s}?.Status; URL="http://localhost:$AppPort/" }
 }
+if (-not $SkipDocs) {
+    $s = Get-Service $SVC_DOCS -ErrorAction SilentlyContinue
+    $rows += [pscustomobject]@{ Component='Docs';     Type='Windows Service';     Name=$SVC_DOCS;    Status=${s}?.Status; URL="http://localhost:$ProxyPort/docs/" }
+}
 if (-not $SkipProxy) {
     $s = Get-Service $SVC_PROXY -ErrorAction SilentlyContinue
     $rows += [pscustomobject]@{ Component='Proxy';    Type='Windows Service';     Name=$SVC_PROXY;   Status=${s}?.Status; URL="http://localhost:$ProxyPort/" }
@@ -635,6 +672,9 @@ if (-not $SkipLogViewer) {
 if (-not $SkipProxy) {
     Write-Host ''
     Write-Host "  Open in browser: http://$(hostname)/" -ForegroundColor Green
+    if (-not $SkipDocs) {
+        Write-Host "  Documentation  : http://$(hostname)/docs/" -ForegroundColor Green
+    }
     if (-not $SkipLogViewer) {
         Write-Host "  Inspect logs   : http://$(hostname)/logs/" -ForegroundColor Green
     }

scripts/deploy/DeployHelpers.psm1

@@ -377,11 +377,32 @@ function Write-NginxConf {
         [string]$AppPort,
         [string]$ProxyPort,
         [string]$LogDir,
-        [string]$LogViewerPort = ''
+        [string]$LogViewerPort = '',
+        [string]$DocsPort = ''
     )
     # nginx requires forward slashes in paths
     $logDirFwd = $LogDir.Replace('\', '/')
 
+    # Optional MkDocs site (mkdocs serve), exposed under /docs/. The trailing
+    # slash on proxy_pass strips the /docs/ prefix because mkdocs serves at root.
+    # WebSocket headers cover mkdocs' livereload; the site renders fine regardless.
+    $docsBlock = ''
+    if ($DocsPort) {
+        $docsBlock = @"
+
+        # MkDocs documentation site
+        location = /docs { return 301 /docs/; }
+        location /docs/ {
+            proxy_pass         http://127.0.0.1:$DocsPort/;
+            proxy_http_version 1.1;
+            proxy_set_header   Upgrade `$http_upgrade;
+            proxy_set_header   Connection "upgrade";
+            proxy_set_header   Host `$host;
+            proxy_set_header   X-Real-IP `$remote_addr;
+        }
+"@
+    }
+
     # Optional OpenObserve log viewer block, exposed under /logs/ (set via
     # ZO_BASE_URI=/logs on the service). Uses the same WebSocket-upgrade headers
     # as the Streamlit block because OpenObserve's UI streams live tail over ws.
@@ -454,6 +475,7 @@ http {
             proxy_set_header Host `$host;
             proxy_set_header X-Real-IP `$remote_addr;
         }
+$docsBlock
 $logViewerBlock
     }
 }

scripts/deploy/EnvironmentProfiles.psm1

@@ -32,6 +32,7 @@ $script:EnvironmentProfiles = @{
         ApiPort       = '8010'
         AppPort       = '8511'
         ProxyPort     = '8080'
+        DocsPort      = '8012'                      # mkdocs serve, exposed via nginx /docs/
         LogViewerPort = '5090'                     # OpenObserve UI, exposed via nginx /logs/
         AllowSeedData = $false                     # dev/demo seed never loaded into staging
     }
@@ -42,6 +43,7 @@ $script:EnvironmentProfiles = @{
         ApiPort       = '8000'
         AppPort       = '8501'
         ProxyPort     = '80'
+        DocsPort      = '8002'                      # mkdocs serve, exposed via nginx /docs/
         LogViewerPort = '5080'                     # OpenObserve UI, exposed via nginx /logs/
         AllowSeedData = $false                     # dev/demo seed never loaded into production
     }