MSI Laptop 3 — API Server Documentation

Ubuntu Server 24.04 host for Python APIs behind Nginx. This folder documents server layout, conventions, and procedures so any technician can deploy or extend the stack without relying on chat history.

Server at a glance

Item	Value
OS	Ubuntu Server 24.04
Hostname	msi-laptop-3
Public static IP (Ethernet enp58s0)	74.83.141.228
Public DNS	hydrotrek.org, www.hydrotrek.org → A → 74.83.141.228
Role	Reverse-proxy host for DWD agent APIs (client gqc)
Edge	Nginx (80/443) → localhost-only app ports 8001–8003
Process manager	systemd (native now; Docker target)
Current phase	First API live; sprint: MCP + Copilot Docker (14-sprint-copilot-mcp-docker.md)

Documentation index

Document	Purpose
docs/01-directory-layout.md	Start here. FHS-aligned paths, ownership, permissions, naming
docs/02-adding-a-new-api.md	Step-by-step checklist to add another API
docs/03-systemd-service.md	systemd unit pattern, env loading, logging
docs/04-nginx-reverse-proxy.md	Subdomain routing, SSL termination (when ready)
docs/05-docker-strategy.md	Docker vs native; what changes on the host
docs/06-dockerizing-dwd-api-fastapi.md	First API container walkthrough
docs/07-code-management-and-git.md	Deploy keys vs personal SSH; Git on server vs registry
docs/08-docker-install-and-users.md	Docker install; gqc / apisvc / docker groups
docs/09-wifi-and-ssh-network-setup.md	Wi‑Fi enable; SSH on wlan only; UFW per interface
docs/10-deploy-dwd-api-fastapi-server.md	Deploy first API on server — Docker copy-paste runbook
docs/11-nginx-lan-setup.md	Nginx port 80 on LAN IP (pre–server room)
docs/12-nvidia-gpu-todo.md	TODO — NVIDIA drivers, nvidia-smi, optional Docker GPU
docs/13-cors-and-browser-api.md	CORS in FastAPI vs Nginx; LAN dev troubleshooting
docs/14-sprint-copilot-mcp-docker.md	Sprint — MCP + Copilot Docker, Nginx, cross-service URLs
docs/16-hydrotrek-org-production-cutover.md	Production — static IP, SSL, DNS, env URLs
templates/	Copy-paste templates for env, systemd, Nginx, Docker, netplan

Standard layout (summary)

/opt/apis/<api-name>/          Application source (git checkout)
/opt/venvs/<api-name>/         Dedicated Python virtual environment
/etc/<api-name>/               Host config and secrets (not in git)
/etc/systemd/system/           systemd unit files
/etc/nginx/sites-available/    Nginx server blocks
/var/log/<api-name>/           Optional file logs (journald is default)

Run all API processes as an unprivileged service account (apisvc) in native mode, bind apps to 127.0.0.1 only, and never expose app ports through the firewall. In Docker mode, map 127.0.0.1:<port>:8080 — see docs/05-docker-strategy.md.

Workstation layout

repos/                         Local git clones (Docker dev, review)
    hydrotrek-dwd-suite/       Super-repo (submodules + stack Docker compose)
    dwd-api-fastapi/           Flat clone (also submodule in suite)
    dwd-mcp-fastmcp/
    dwd-copilot-server/
docs/                          Server runbooks
templates/                     Config and Docker templates
scripts/                       Server setup scripts

Stack orchestration (Compose, dwd-stack network, Nginx path routing): repos/hydrotrek-dwd-suite/docker/. Per-service Dockerfile files stay in each submodule repo.

Server paths (/opt/apis/, /etc/<api-name>/) are documented in docs/01-directory-layout.md.

Completed on server

• SSH with key authentication from Windows workstation
• Laptop power management (suspend masked; logind lid settings verified)
• Base packages: nginx, git, curl, unzip, python3, python3-pip, python3-venv, ufw
• NVIDIA driver: nvidia-driver-595-open — nvidia-smi OK (RTX 4070 Max-Q, 595.71.05)

Deferred / in progress

• UFW enable — per-interface rules: SSH on Wi‑Fi only; 80/443 on Ethernet (enp58s0) — docs/09-wifi-and-ssh-network-setup.md
• sshd ListenAddress bound to Wi‑Fi IP (same doc)
• Static IP: 74.83.141.228 — full cutover checklist: docs/16-hydrotrek-org-production-cutover.md

Wi‑Fi (enable before or during office setup)

• Headless Server may need wpasupplicant, firmware-iwlwifi, and netplan Wi‑Fi config
• Ethernet = production; Wi‑Fi = admin SSH path (behind VPN)
• Full runbook: docs/09-wifi-and-ssh-network-setup.md

Open decisions

Topic	Current choice	Notes
Routing	Subdomains (preferred)	e.g. customer.example.com
Deployment	TBD	Manual git pull vs CI/CD
Runtime	Native first → Docker	Boss requirement; see docker docs
SSL	Existing cert via Nginx	Let's Encrypt optional later
Azure auth	Service principal or SAS	Secrets in /etc/<api-name>/

Deployed APIs

Service	Repo	Container port	Host (127.0.0.1)	Nginx (LAN)	Status
dwd-api-fastapi	repos/dwd-api-fastapi	8080	8001	/gqc/api/fastapi/	deploy doc
dwd-mcp-fastmcp	repos/dwd-mcp-fastmcp	8081	8002	/gqc/api/mcp	Stack: hydrotrek-dwd-suite/docker
dwd-copilot-server	repos/dwd-copilot-server	8082	8003	/gqc/api/copilotkit	Stack: hydrotrek-dwd-suite/docker

Browser: https://www.hydrotrek.org/gqc/api/... (public). / returns 404. Docker DNS unchanged.

Sprint checklist (MCP + Copilot): docs/14-sprint-copilot-mcp-docker.md

TODO

Item	Status	Doc
NVIDIA nvidia-smi installed and working	Done (595.71.05, RTX 4070 Max-Q)	docs/12-nvidia-gpu-todo.md