📚 Documentation Issue Summary

The repository currently lacks comprehensive onboarding documentation to help new developers set up their local environment. This can slow down contributors unfamiliar with Python-based FastAPI projects, container tools, and cross-platform setup nuances.

📍 Location of the Problem

Suggested location: docs/docs/development/developer-workstation.md

✏️ Type of Issue

• Missing explanation or example
• Unclear instructions

💡 Suggested Fix or Clarification

Create a new markdown page under the existing MkDocs documentation structure at:

docs/docs/development/developer-workstation.md

And update the .pages file to link to this new page,

Include the following:

• Tooling Requirements:

  • Python (>= 3.10)
  • Docker or Podman - and information on install docker.io, buildx and docker-compose v2 (free), or podman-desktop
  • Setting up permissions for docker or rootless podman
  • Docker Compose or compatible wrapper setup
  • GNU Make (for using provided Makefile)
  • (Optional) uv, ruff, mypy, isort
  • node.js and npm for the various linters used for the HTML / CSS / JS UI
  • (Optional) Visual Studio Code and useful plugins

• OS-Specific Notes:

  • macOS: cover Homebrew installation for Intel & Apple Silicon

  • Linux: apt/dnf-based install tips, user permission notes for Docker

  • Windows:

    • Recommend WSL2
    • Explain issues with file paths and volume mounting
    • Explain issues with running podman inside WSL2 and exposing ports, etc.
    • Use of Windows Terminal and make alternatives if needed

• Common Gotchas:

  • Docker socket permissions
  • .venv activation across shells
  • Port 4444 already in use

• Include snippet examples:

  make venv install serve

🧩 Additional Notes

The README.md and existing contain partial info already, but this doc will serve as a consolidated and beginner-friendly guide that focuses on prereqs on the developer workstation, and link to those other pages.

Signing commits

Add information to the main development page on how to sign your comments, and correctly setup gitconfig.

Example:

# ~/.gitconfig
# Git configuration for Mihai Criveti
# Ensures consistent LF line endings, meaningful defaults, and signed-off commits

[user]
    name = Your Name
    email = your-exail@example.com

[init]
    defaultBranch = main  # Use 'main' instead of 'master' when creating new repos

[core]
    autocrlf = input       # On commit: convert CRLF to LF (Windows → Linux)
                           # On checkout: leave LF alone (no conversion)
    eol = lf               # Ensure all files in the repo use LF internally

[alias]
    cm = commit -s -m      # Short alias: 'git cm "message"' creates signed-off commit
    ca = commit --amend -s # Amend last commit and ensure it has a Signed-off-by trailer

[commit]
    # Uncomment this if you want to auto-insert a commit message template with sign-off
    template = ~/.git-commit-template