Skip to content

Dockerized MkDocs Deployment (docs.hadox.org)

This document describes how the documentation site hosted at https://docs.hadox.org is built, deployed, and served using Docker and Nginx on our VPS infrastructure.

1. Project Structure

The documentation is version-controlled under the madlabs-docs repository.

madlabs-docs/
├── Dockerfile
├── docker-compose.yml
├── mkdocs.yml
└── docs/
    ├── index.md
    ├── infrastructure/
    ├── workflows/
    ├── apps/
    ├── dev-onboarding/
    └── meta/

2. Docker Setup

The MkDocs site runs as a container using the official squidfunk/mkdocs-material image.

Dockerfile

FROM squidfunk/mkdocs-material
WORKDIR /docs
COPY . .
EXPOSE 8000
CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]

docker-compose.yml

services:
  mkdocs:
    build: .
    ports:
      - "8005:8000"
    volumes:
      - .:/docs

3. Nginx Reverse Proxy

The site is proxied through Nginx and accessible via HTTPS.

Domain

  • docs.hadox.org points to port 8005 on the VPS

SSL Certificates

  • Managed with Certbot
  • Automatically renewed with cron

4. Update Process

To deploy updates:

From Local

# On local machine
git add .
git commit -m "docs: update section X"
git push origin main

On VPS

# SSH into VPS
cd /home/madlabs-docs
git pull origin main
docker compose up -d --build

5. Troubleshooting

  • git pull might fail if local Dockerfile/docker-compose.yml differ — backup and retry
  • Use docker logs madlabs-docs to inspect errors
  • Use sudo nginx -t && sudo systemctl reload nginx after any reverse proxy changes

6. Future Improvements

  • Consider GitHub Webhooks to automate pull & rebuild
  • Document site versioning and changelogs automatically