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)

python -m mkdocs serve

Alternative (explicit binary from venv):

./.venv/bin/mkdocs serve

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

Build image

docker compose build

Start the static site

docker compose up

Open: http://127.0.0.1:8080

Rebuild and start in one command

docker compose up --build