Scaffold FastAPI + MySQL + Keycloak service with devcontainer

Sets up the project skeleton:

- FastAPI app factory with lifespan, request-id middleware, and RFC 9457
  problem+json error handlers
- Async SQLAlchemy 2.0 over MySQL (asyncmy), with a constraint naming
  convention in place before the first migration and async Alembic
- Keycloak as a pure resource server: OIDC discovery, cached JWKS with
  rotation-aware refresh, and require_roles dependencies
- Devcontainer running MySQL 8.4 and Keycloak 26.7 as compose siblings,
  with the realm (clients, roles, test users) imported on first boot
- Test suite covering the endpoints plus the token validator itself,
  exercised against a locally generated RSA keypair
- uv packaging, ruff, mypy --strict, pre-commit, Gitea CI, prod Dockerfile

Two Keycloak-in-containers traps are handled explicitly and documented in
the README: the issuer/internal-URL split (the browser sees localhost:8080,
the API sees keycloak:8080) and the audience mapper that stops Keycloak
issuing tokens with aud=account.

The devices resource is a placeholder proving the routing -> auth -> ORM ->
migration path end to end; replace it with the real domain.

Co-Authored-By: Claude Opus 5 <[email protected]>

.devcontainer/Dockerfile

@@ -0,0 +1,16 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.13-bookworm
+
+# `mysql` CLI for poking at the database during development.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends default-mysql-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Pinned rather than :latest so a rebuild months from now is reproducible.
+COPY --from=ghcr.io/astral-sh/uv:0.9.7 /uv /uvx /usr/local/bin/
+
+ENV UV_PROJECT_ENVIRONMENT=/workspaces/v2x-server/.venv \
+    # Bind mounts can't be hardlinked into, which is uv's default install mode.
+    UV_LINK_MODE=copy \
+    UV_COMPILE_BYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH=/workspaces/v2x-server/.venv/bin:$PATH

.devcontainer/compose.override.yaml

@@ -0,0 +1,44 @@
+# Adds the development container to the stack defined in ../compose.yaml.
+# Merged by devcontainer.json; not useful on its own.
+
+services:
+  app:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+    command: sleep infinity
+    ports:
+      - "8000:8000"
+    volumes:
+      - ..:/workspaces/v2x-server:cached
+      # Keep the Linux venv out of the macOS/Windows bind mount. Without this,
+      # host-side tooling and platform-specific wheels collide.
+      - venv:/workspaces/v2x-server/.venv
+    environment:
+      APP_ENV: local
+      DEBUG: "true"
+      DATABASE_URL: mysql+asyncmy://v2x:v2xpassword@mysql:3306/v2x?charset=utf8mb4
+      TEST_DATABASE_URL: mysql+asyncmy://v2x:v2xpassword@mysql:3306/v2x_test?charset=utf8mb4
+      # Validated against the `iss` claim -- must match the URL the browser used
+      # to obtain the token, not the one this container dials.
+      KEYCLOAK_ISSUER: http://localhost:8080/realms/v2x
+      # Where this container actually reaches Keycloak for discovery + JWKS.
+      # KC_HOSTNAME_BACKCHANNEL_DYNAMIC makes discovery hand back a jwks_uri on
+      # this same host, so the fetch stays on the compose network.
+      KEYCLOAK_INTERNAL_URL: http://keycloak:8080
+      KEYCLOAK_REALM: v2x
+      KEYCLOAK_AUDIENCE: v2x-api
+      KEYCLOAK_SWAGGER_CLIENT_ID: v2x-swagger
+      CORS_ORIGINS: '["http://localhost:3000","http://localhost:8000"]'
+    depends_on:
+      # Migrations need a live database, so wait for MySQL properly.
+      mysql:
+        condition: service_healthy
+      # Keycloak is only contacted lazily, on the first token validation. Not
+      # blocking on its health keeps a slow or failed realm import from
+      # preventing the devcontainer from opening at all.
+      keycloak:
+        condition: service_started
+
+volumes:
+  venv:

.devcontainer/devcontainer.json

@@ -0,0 +1,41 @@
+{
+  "name": "v2x-server",
+  "dockerComposeFile": ["../compose.yaml", "compose.override.yaml"],
+  "service": "app",
+  "workspaceFolder": "/workspaces/v2x-server",
+  "shutdownAction": "stopCompose",
+
+  "forwardPorts": [8000, 8080, 3306],
+  "portsAttributes": {
+    "8000": { "label": "API", "onAutoForward": "notify" },
+    "8080": { "label": "Keycloak", "onAutoForward": "silent" },
+    "3306": { "label": "MySQL", "onAutoForward": "silent" }
+  },
+
+  // The venv lives on a named volume owned by root until first use.
+  "postCreateCommand": "sudo chown vscode:vscode .venv && uv sync --frozen && uv run pre-commit install",
+
+  "remoteUser": "vscode",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "ms-python.mypy-type-checker",
+        "tamasfe.even-better-toml"
+      ],
+      "settings": {
+        "python.defaultInterpreterPath": "/workspaces/v2x-server/.venv/bin/python",
+        "python.testing.pytestEnabled": true,
+        "python.testing.pytestArgs": ["tests"],
+        "editor.formatOnSave": true,
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.codeActionsOnSave": { "source.organizeImports": "explicit" }
+        }
+      }
+    }
+  }
+}