notes

A living, versioned base of technical notes: architecture, data, security, tooling, and systems. Published as documentation.

How to run

Why this project uses venv + pip

If you installed mkdocs globally with apt, keep it if you want. For this repository, use a local virtual environment so dependency versions (including Material theme) are isolated and reproducible.

1) Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate

2) Install dependencies

python -m pip install -r requirements.txt

3) Verify Material theme is installed (optional)

python -m mkdocs --version
python -m pip show mkdocs-material

4) Run locally (preview)

mkdocs serve --livereload

Open: http://127.0.0.1:8000

5) Build static site

python -m mkdocs build

The site will be generated in the site/ folder.

Run with Docker Compose

Builds the site and serves static files with Nginx (no watch).

docker compose build

Start the static site

docker compose up

Open: http://127.0.0.1:8081

Rebuild and start in one command

docker compose up --build