mkdocs.yml

site_name: Engineering Docs
site_url: https://engineering-docs.internal.minhdq.dev
site_description: Internal engineering documentation for minhdqdev-org

repo_name: minhdqdev-org/engineering-docs
repo_url: https://github.com/minhdqdev-org/engineering-docs

theme:
  name: material
  features:
    - content.action.edit
    - content.action.view
    - content.code.annotate
    - content.code.copy
    - content.tooltips
    - navigation.footer
    - navigation.indexes
    - navigation.sections
    - navigation.tabs
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/link
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/toggle-switch-off
        name: Switch to system preference
  font:
    text: Roboto
    code: Roboto Mono

plugins:
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - tags
  - minify:
      minify_html: true

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/minhdqdev-org

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Architecture:
    - architecture/index.md
    - DSTA:
      - High-Level Design: architecture/dsta/index.md
      - Onboarding: architecture/dsta/onboarding.md
      - Diagrams: architecture/dsta/diagrams/README.md
      - Data Model (ERD): architecture/dsta/diagrams/erd.md
      - API Contracts: architecture/dsta/api.md
  - Homelab:
    - Overview: homelab/intro.md
    - Architecture & Design:
      - Network Architecture: homelab/network-architecture.md
      - Design Decisions: homelab/design-decisions.md
      - VLANs: homelab/vlan.md
      - Access Control (ACLs): homelab/acl.md
      - Service Catalog: homelab/service-catalog.md
    - Proxmox Hosts:
      - ws01 — Proxmox VE Host: homelab/ws/ws01.md
      - ws02 (Decommissioned): homelab/ws/ws02.md
      - Proxmox Cluster Setup: homelab/ws/proxmox-cluster.md
      - Silent Kill Detection & Recovery: homelab/ws/proxmox-silent-kill-detection.md
    - Virtual Machines:
      - vm101 — DevOps Workstation: homelab/vm/vm101.md
      - vm101 SSH Internet Access: homelab/vm/vm101-ssh-internet-access.md
      - vm102 — Production Services: homelab/vm/vm102.md
      - vm105 — OpenClaw AI Agent: homelab/vm/vm105-openclaw.md
      - vm112 — Neko Farm Worker: homelab/vm/vm112.md
      - Kubernetes Networking Notes: homelab/vm/k8s-networking.md
      - CoreDNS / systemd-resolved Fix: homelab/vm/dns-systemd-resolved-fix.md
    - Containers (LXC):
      - gw01 — Gateway: homelab/ct/gw01.md
      - dns01 — BIND9 DNS: homelab/ct/dns01-bind.md
      - ts01 — Tailscale Subnet Router: homelab/ct/ts01-subnet-router.md
      - warp01 — VPN Gateway & Proxy: homelab/ct/warp01.md
      - jump01 — Bastion (decommissioned): homelab/ct/jump01-bastion.md
      - jump02 — Bastion (decommissioned): homelab/ct/jump02-bastion.md
      - Fail2Ban + Nginx + Cloudflare: homelab/ct/fail2ban-cloudflare.md
      - Grafana: homelab/ct/grafana.md
      - Prometheus: homelab/ct/prometheus.md
      - Tempo: homelab/ct/tempo.md
      - OpenSearch: homelab/ct/opensearch.md
      - OTel Collector: homelab/ct/otel-collector.md
      - Uptime Kuma: homelab/ct/uptimekuma.md
    - Services:
      - ArgoCD: homelab/srv/argocd.md
      - Harbor Container Registry: homelab/srv/harbor.md
      - Vault Service & Injector: homelab/srv/hashicorp-vault.md
      - Keycloak SSO Integration: homelab/srv/keycloak.md
      - Keycloak Documentation Guide: homelab/srv/keycloak-documentation-guide.md
      - Kong Gateway: homelab/srv/kong.md
      - PostgreSQL Operations: homelab/srv/minhdq-postgres.md
      - Redis Cache: homelab/srv/redis.md
      - RabbitMQ: homelab/srv/rabbitmq.md
      - Kafka: homelab/srv/kafka.md
      - MinIO Object Storage: homelab/srv/minio.md
      - NFS Provisioner: homelab/srv/nfs.md
      - NotiHub: homelab/srv/notihub.md
      - Neko Farm (Browser Pool): homelab/srv/neko-farm.md
      - DSTA Service: homelab/srv/dsta.md
      - Backstage (IDP): homelab/srv/backstage.md
      - Homepage Dashboard: homelab/srv/homepage.md
      - Jellyfin (GPU): homelab/srv/jellyfin.md
      - Paperclip: homelab/srv/paperclip.md
      - Portainer: homelab/srv/portainer.md
      - Syncthing: homelab/srv/syncthing.md
      - Vaultwarden: homelab/srv/vaultwarden.md
      - VNC Remote Desktop: homelab/srv/vnc.md
      - Playwright Testing: homelab/srv/playwright-testing.md
      - GitHub Actions Runners: homelab/srv/github-actions-runners.md
      - Homelab Docs Pipeline: homelab/srv/homelab-docs.md
      - Shared Services: homelab/srv/shared-services.md
      - Synthetic Uptime Monitoring: homelab/srv/uptime-monitoring.md
    - Observability:
      - Current Architecture: homelab/srv/observability/observability-current.md
      - Prometheus + Thanos (historical): homelab/srv/observability/prometheus-thanos.md
      - Loki (historical): homelab/srv/observability/loki.md
      - Tempo Tracing: homelab/srv/observability/tempo.md
      - Alertmanager Routing: homelab/srv/observability/alertmanager.md
      - Disk Monitoring: homelab/srv/observability/disk-monitoring.md
      - K8s Cert Expiry Monitoring: homelab/srv/observability/k8s-cert-monitoring.md
    - Tenants:
      - minhdqdev-org: homelab/tenants/minhdqdev-org.md
      - Linhan Studio: homelab/tenants/linhan-studio.md
      - Overcoded: homelab/tenants/overcoded.md
    - Automation:
      - Kubernetes Node Failure Recovery: homelab/automation/node-failure-recovery.md
      - Obsidian Vault Sync: homelab/automation/obsidian-vault-sync.md
    - Incidents:
      - gw01 eth1/vmbr1 Down on Boot: homelab/incidents/gw01-eth1-vmbr1-down-on-boot.md
      - vm101 Memory Reporting (>100%): homelab/incidents/vm101-memory-reporting-fix.md
    - Operations:
      - Operations Quickstart: homelab/operations-quickstart.md
      - External User Access: homelab/external-user-access.md
      - PBS Backup Plan: homelab/pbs-plan.md
      - Shrink Disk (Proxmox): homelab/shrink-disk.md
    - Proposals & Ideas:
      - Platform Strategy: homelab/ideas/strategy.md
      - Hardware Recommendations: homelab/ideas/hardware-recommendations.md
      - etcd Improvement Ideas: homelab/ideas/etcd-improvement-idea.md
      - KEDA Scale-to-Zero: homelab/ideas/keda-idea.md
      - Paperclip Deployment Plan: homelab/ideas/paperclip.md
      - Raspberry Pi QDevice Setup: homelab/ideas/rbp-setup.md
      - Todoist → Todopro Migration: homelab/ideas/todoist-migration.md
      - vm102 Disk Optimization: homelab/ideas/vm102-disk-optimization.md
      - m99-mbp Workstation Setup: homelab/ideas/ansible-account-on-mbp.md
  - Runbooks:
    - runbooks/index.md
    - DSTA: runbooks/dsta.md
  - ADRs:
    - adrs/index.md
    - DSTA:
      - adrs/dsta/index.md
      - adrs/dsta/0001-microservices-decomposition.md
      - adrs/dsta/0002-framework-split-django-fastapi.md
      - adrs/dsta/0003-arq-over-celery.md
      - adrs/dsta/0004-shared-postgres-per-service-alembic.md
      - adrs/dsta/0005-cross-service-jwt-auth.md
      - adrs/dsta/0006-timescaledb-for-ohlcv.md
      - adrs/dsta/0007-fernet-encryption-exchange-keys.md
      - adrs/dsta/0008-pgvector-rag.md
      - adrs/dsta/0009-frontend-react-vite-bun.md
      - adrs/dsta/0010-kubernetes-argocd-gitops.md
      - adrs/dsta/0011-rest-openapi-no-grpc.md
      - adrs/dsta/0012-multi-repo-strategy.md