Docs — Documentation Site¶

The AKKO Docs service serves the MkDocs Material documentation site as a containerized nginx deployment inside the Kubernetes cluster. It provides bilingual (EN/FR) documentation for all AKKO services, architecture, administration guides, and starter kits.

Architecture¶

Browser
   |
+--v-----------+
|  Traefik     |
|  (ingress)   |
+--+-----------+
   |
+--v-----------+
|  akko-docs   |
|  (nginx :80) |
|  MkDocs HTML |
+--------------+

akko-docs image is built from the docs/ directory using MkDocs Material
Nginx serves the pre-built static HTML site
Optionally mounts a shared PVC for Quarto-rendered reports from JupyterHub

URLs¶

Mode	URL
Kubernetes (k3d)	`https://docs.<domain>`

Configuration (Helm values)¶

akko-docs:
  enabled: true
  image:
    repository: docs
    tag: "2026.03"
  service:
    port: 80
  ingress:
    enabled: true
    host: "docs.akko.local"
  publishedReports:
    enabled: false    # Enable to serve /reports/ with Quarto HTML
    size: 1Gi
  resources:
    requests:
      cpu: 50m
      memory: 32Mi
    limits:
      cpu: 100m
      memory: 64Mi

Health Check¶

Nginx responds to HTTP requests on port 80:

livenessProbe:
  httpGet:
    path: /
    port: 80
  initialDelaySeconds: 5
  periodSeconds: 30
readinessProbe:
  httpGet:
    path: /
    port: 80
  initialDelaySeconds: 3
  periodSeconds: 10

RBAC (who can access)¶

The documentation site is publicly accessible through the ingress (no authentication required). It contains only public documentation — no secrets or confidential information.

Building the Image¶

The docs image is built by helm/scripts/build-images.sh:

docker build -t akko-docs:2026.03 -f docs/Dockerfile docs/

To preview locally before building:

cd docs && mkdocs serve

Key Features¶

Feature	Description
Bilingual	Full EN + FR translation via mkdocs-i18n plugin
Material theme	Dark/light mode, search, navigation tabs
Quarto reports	Optional shared PVC for notebook-rendered reports
Lightweight	32 Mi RAM, static HTML only

Resource Requirements¶

Component	Minimum RAM	Recommended
Docs (nginx)	32 Mi	64 Mi

Troubleshooting¶

Docs Site Returns 404¶

Symptoms: Navigating to https://docs.<domain> returns a 404 or blank page.

Cause: The docs image was not rebuilt after documentation changes, or the image tag in values does not match the built image.

Solution:

# Check the pod is running
kubectl get pods -n akko -l app.kubernetes.io/name=akko-docs

# Verify the image tag
kubectl describe pod -n akko -l app.kubernetes.io/name=akko-docs | grep Image

# Rebuild and redeploy
bash helm/scripts/build-images.sh
helm upgrade akko helm/akko/ -n akko -f <values-files>

Stale Documentation After Update¶

Symptoms: Documentation content is outdated despite recent commits.

Cause: The docs image cache was not invalidated during the build.

Solution:

# Force rebuild without cache
docker build --no-cache -t akko-docs:2026.03 -f docs/Dockerfile docs/

# Reimport to k3d
k3d image import akko-docs:2026.03 -c akko

# Restart the pod
kubectl rollout restart -n akko deploy/akko-akko-docs