Migrate the backend from pip to uv

Replace requirements.txt with a uv workspace and lockfile, install the five tavolo packages from packages/* in development and non-editable in the image, and build the Docker image with uv. Move dev tools to a PEP 735 dependency group and refresh the locked dependency versions.

.dockerignore

@@ -7,11 +7,11 @@
 .env.example
 **/.venv/
 **/__pycache__/
-*.pyc
+**/*.pyc
-*.pyo
+**/*.pyo
-*.egg-info/
+**/*.egg-info/
-.mypy_cache/
+**/.mypy_cache/
-.pytest_cache/
+**/.pytest_cache/
 web/target/
 web/dist/
 server/tests/

README.md

@@ -110,20 +110,22 @@ live-play websocket lives.
 
 ## Development
 
-Backend (from `server/`):
+Backend (from `server/`), using [uv](https://docs.astral.sh/uv/):
 
 ```sh
 cd server
-python3 -m venv .venv
+uv sync --package tavolo-app --extra otel
-.venv/bin/pip install -r requirements.txt
+uv run python -m unittest discover -s tests -t .
-.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e ./packages/tavolo-scopa -e ./packages/tavolo-briscola -e './packages/tavolo-app[dev]'
+uv run python -m unittest discover -s packages/tavolo-platform/tests
-.venv/bin/python -m unittest discover -s tests -t .
+uv run python -m unittest discover -s packages/tavolo-scopone/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
+uv run python -m unittest discover -s packages/tavolo-scopa/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
+uv run python -m unittest discover -s packages/tavolo-briscola/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-scopa/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
 ```
 
+The `otel` extra is optional; without it the telemetry integration tests
+skip. Development tools (`mypy`, `httpx-ws`) are installed by default from
+the workspace's `dev` dependency group.
+
 Frontend (from `web/`), with the backend running on :8080:
 
 ```sh
@@ -142,7 +144,7 @@ OIDC_0_CLIENT_ID=tavolo \
 OIDC_0_REDIRECT_URI=http://localhost:8080/auth/default/callback \
 OIDC_0_POST_LOGIN_REDIRECT=http://localhost:8000/ \
 OIDC_0_POST_LOGOUT_REDIRECT=http://localhost:8000/ \
-  .venv/bin/granian --host 127.0.0.1 --port 8080 tavolo.app:app
+  uv run granian --host 127.0.0.1 --port 8080 tavolo.app:app
 ```
 
 Card images are committed under `web/assets/cards/`; `web/fetch-cards.sh`

docker-compose.yml

@@ -128,7 +128,7 @@ services:
       # (HTTP/WebSocket, Postgres, Redis), metrics and logs via OTLP/HTTP,
       # disabled unless OTEL_ENABLED is set.
       # The image bundles the otel extra (see packages/tavolo-app/pyproject.toml
-      # and server/requirements.txt).
+      # and server/uv.lock).
       OTEL_ENABLED: ${OTEL_ENABLED:-}
       OTEL_SERVICE_NAME: ${OTEL_SERVICE_NAME:-}
       OTEL_EXPORTER_OTLP_ENDPOINT: ${OTEL_EXPORTER_OTLP_ENDPOINT:-}

server/.python-version

@@ -0,0 +1 @@
+3.14

server/Dockerfile

@@ -7,7 +7,7 @@
 #   builder      alpine python -> python venv with the backend + deps
 #   runtime      alpine python + the venv + the compiled frontend
 #
-# apk and pip both use BuildKit cache mounts (type=cache): the package
+# apk and uv both use BuildKit cache mounts (type=cache): the package
 # caches persist in the builder's cache across builds instead of being
 # re-downloaded, and never land in the image layers.
 
@@ -49,29 +49,43 @@ RUN --mount=type=cache,target=/usr/local/cargo/registry \
 # --- Python builder ----------------------------------------------------------
 FROM alpine:3.24 AS builder
 
+# The official uv image ships a statically linked musl binary, so it works
+# on Alpine. Pin the version so image builds do not change implicitly.
+COPY --from=ghcr.io/astral-sh/uv:0.13.1 /uv /uvx /bin/
+
 RUN --mount=type=cache,target=/var/cache/apk \
-    apk add python3 py3-pip build-base python3-dev
+    apk add python3 build-base python3-dev
+
+# Use Alpine's Python instead of downloading a managed interpreter, install
+# the venv at the same path the runtime stage uses, and copy rather than
+# hardlink from the cache mount (cache and target are different filesystems).
+ENV UV_PYTHON_DOWNLOADS=0 \
+    UV_PROJECT_ENVIRONMENT=/opt/venv \
+    UV_LINK_MODE=copy
 
 WORKDIR /build
 
+# uv needs the workspace root plus the member pyprojects to know which
+# package to sync. Copying only the manifests lets the third-party
+# dependency layer stay cached while application sources change.
+# server/pyproject.toml also carries [tool.aerich], read by the db-migrate
+# compose service with working_dir=/app, next to ./migrations.
+COPY server/uv.lock server/pyproject.toml ./
+COPY server/packages/tavolo-platform/pyproject.toml packages/tavolo-platform/
+COPY server/packages/tavolo-scopone/pyproject.toml packages/tavolo-scopone/
+COPY server/packages/tavolo-scopa/pyproject.toml packages/tavolo-scopa/
+COPY server/packages/tavolo-briscola/pyproject.toml packages/tavolo-briscola/
+COPY server/packages/tavolo-app/pyproject.toml packages/tavolo-app/
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-install-workspace --package tavolo-app --extra otel --no-dev
 
-COPY server/requirements.txt ./
+# The five sibling distributions are workspace members (PEP 420 namespace
-RUN --mount=type=cache,target=/root/.cache/pip \
+# packages sharing the `tavolo` namespace). --no-editable installs them as
-    python3 -m venv /opt/venv \
+# wheels, so the runtime image does not need their source tree.
- && /opt/venv/bin/pip install --upgrade pip \
- && /opt/venv/bin/pip install -r requirements.txt
-
-# The five sibling distributions, installed from the local tree (PEP 420
-# namespace packages sharing the `tavolo` namespace). --no-deps: every
-# third-party dependency — including the tavolo-app `otel` extra — is
-# already pinned in requirements.txt.
 COPY server/packages/ ./packages/
-RUN --mount=type=cache,target=/root/.cache/pip \
+RUN --mount=type=cache,target=/root/.cache/uv \
-    /opt/venv/bin/pip install --no-deps ./packages/tavolo-platform ./packages/tavolo-scopone ./packages/tavolo-scopa ./packages/tavolo-briscola ./packages/tavolo-app
+    uv sync --locked --no-editable --package tavolo-app --extra otel --no-dev
-# server/pyproject.toml only carries the [tool.aerich] section (the
+
-# db-migrate compose service runs `aerich upgrade` with working_dir=/app,
-# next to ./migrations).
-COPY server/pyproject.toml ./
 # aerich migration files are a release artifact: the db-migrate compose
 # service runs `aerich upgrade` from this image before the app starts.
 COPY server/migrations/ ./migrations/

server/README.md

@@ -99,7 +99,7 @@ All configuration comes from environment variables (see `.env.example`):
 | `CORS_ALLOW_CREDENTIALS` | `false` | `1`/`true`/`yes`/`on` allow cookies/credentials on cross-origin requests |
 | `CORS_EXPOSE_HEADERS` | unset | Comma-separated response headers exposed to the browser |
 | `CORS_MAX_AGE` | `600` | Seconds browsers may cache the preflight response |
-| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces, metrics and logs (the Docker image bundles the `otel` extra; non-image installs need `pip install tavolo-app[otel]`) |
+| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces, metrics and logs (the Docker image bundles the `otel` extra; non-image installs need `uv sync --package tavolo-app --extra otel`) |
 | `OTEL_SERVICE_NAME` | `tavolo` | `service.name` resource attribute of the exported telemetry |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | Base URL of an OTLP/HTTP collector (e.g. `http://localhost:4318`); unset uses the exporter default |
 | `OTEL_EXPORTER_OTLP_HEADERS` | unset | Comma-separated `key=value` headers sent to the collector (e.g. authentication) |
@@ -276,7 +276,7 @@ rebuild every rating and aggregate from the recorded match history (e.g.
 to backfill matches recorded before ratings existed):
 
 ```sh
-.venv/bin/python -m tavolo.platform.backfill_elo \
+uv run python -m tavolo.platform.backfill_elo \
   --database-url postgres://tavolo:tavolo@localhost:5432/tavolo
 ```
 
@@ -511,24 +511,33 @@ rejected with an `illegal_move` error.
 
 ## Development
 
+The backend is a [uv](https://docs.astral.sh/uv/) workspace: `pyproject.toml`
+declares the five packages under `packages/` as members, and `uv.lock` pins
+their full dependency closure. The checked-in `.python-version` selects
+Python 3.14, matching the Docker image. Install uv, then from `server/`:
+
 ```sh
-python3 -m venv .venv
+uv sync --package tavolo-app --extra otel
-.venv/bin/pip install -r requirements.txt
-.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e ./packages/tavolo-scopa -e ./packages/tavolo-briscola -e './packages/tavolo-app[dev]'
 # app integration suite:
-.venv/bin/python -m unittest discover -s tests -t .
+uv run python -m unittest discover -s tests -t .
 # per-package suites (each package is self-contained):
-.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
+uv run python -m unittest discover -s packages/tavolo-platform/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
+uv run python -m unittest discover -s packages/tavolo-scopone/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-scopa/tests
+uv run python -m unittest discover -s packages/tavolo-scopa/tests
-.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
+uv run python -m unittest discover -s packages/tavolo-briscola/tests
 # type checks (see packages/tavolo-app/README.md for the app modules):
-.venv/bin/python -m mypy -p tavolo.platform
+uv run mypy -p tavolo.platform
-.venv/bin/python -m mypy -p tavolo.scopone
+uv run mypy -p tavolo.scopone
-.venv/bin/python -m mypy -p tavolo.scopa
+uv run mypy -p tavolo.scopa
-.venv/bin/python -m mypy -p tavolo.briscola
+uv run mypy -p tavolo.briscola
 ```
 
+`uv sync` installs the workspace's `dev` dependency group (`mypy`,
+`httpx-ws`) automatically; pass `--no-dev` for a runtime-only environment.
+The `otel` extra is optional, but without it the telemetry integration tests
+skip. The lockfile is committed: use `uv lock --upgrade` (or
+`uv lock --upgrade-package <name>`) to update dependencies deliberately.
+
 Tests run fully in-process: in-memory sqlite for Postgres, in-memory stores
 for Redis, a fake OIDC user patched onto the mixins, and `httpx` /
 `httpx-ws` ASGI transports for HTTP and WebSocket coverage. The platform
@@ -543,8 +552,8 @@ To add a migration after changing
 `packages/tavolo-platform/src/tavolo/platform/models.py`:
 
 ```sh
-DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo .venv/bin/aerich migrate
+DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo uv run aerich migrate
-DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo .venv/bin/aerich upgrade
+DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo uv run aerich upgrade
 ```
 
 (`aerich init-db` produces sqlite-flavored DDL when pointed at sqlite;
@@ -605,7 +614,8 @@ packages/tavolo-app/          # deployable app: composition root (own pyproject)
   ├── aerich_config.py        # aerich CLI configuration
   ├── logging_config.py       # logging setup
   └── static.py               # SPA shell hosting
-pyproject.toml                # tooling shim: [tool.aerich] + [tool.mypy] for server/ CWD
+pyproject.toml                # uv workspace root + [tool.aerich] / [tool.mypy]
+uv.lock                       # locked dependency set for the whole workspace
 migrations/                   # aerich migrations for the platform models
 tests/                        # app integration suite (platform + games wired together)
 ```

server/packages/tavolo-app/README.md

@@ -29,7 +29,7 @@ The deployable tavolo application: the composition root wiring
 ## Development (from `packages/tavolo-app/`)
 
 ```sh
-.venv/bin/python -m mypy --namespace-packages --explicit-package-bases \
+uv run mypy --namespace-packages --explicit-package-bases \
   src/tavolo/app.py \
   src/tavolo/config.py \
   src/tavolo/telemetry.py \

server/packages/tavolo-app/pyproject.toml

@@ -31,10 +31,6 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = [
-    "mypy",
-    "httpx-ws",
-]
 otel = [
     "kaya-otel>=0.0.7",
     "opentelemetry-instrumentation-asyncpg>=0.66b0",
@@ -42,6 +38,12 @@ otel = [
     "opentelemetry-instrumentation-system-metrics>=0.66b0",
 ]
 
+[dependency-groups]
+dev = [
+    "mypy",
+    "httpx-ws",
+]
+
 [tool.setuptools.packages.find]
 where = ["src"]
 namespaces = true

server/packages/tavolo-briscola/README.md

@@ -92,8 +92,8 @@ the match), so the hand-ack timeout is accepted but unused.
 ## Development (from `server/`)
 
 ```sh
-.venv/bin/python -m unittest discover -s packages/tavolo-briscola/tests
+uv run python -m unittest discover -s packages/tavolo-briscola/tests
-.venv/bin/python -m mypy -p tavolo.briscola
+uv run mypy -p tavolo.briscola
 ```
 
 `test_engine.py`/`test_plugin.py` cover the two classic variants;

server/packages/tavolo-platform/README.md

@@ -58,8 +58,8 @@ examples are [`tavolo-scopone`](../tavolo-scopone/README.md),
 ## Development (from `server/`)
 
 ```sh
-.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
+uv run python -m unittest discover -s packages/tavolo-platform/tests
-.venv/bin/python -m mypy -p tavolo.platform
+uv run mypy -p tavolo.platform
 ```
 
 Tests run fully in-process against a `DummyEngine` (a two-player toy game

server/packages/tavolo-scopa/README.md

@@ -36,8 +36,8 @@ application composition root.
 ## Development (from `server/`)
 
 ```sh
-.venv/bin/python -m unittest discover -s packages/tavolo-scopa/tests
+uv run python -m unittest discover -s packages/tavolo-scopa/tests
-.venv/bin/python -m mypy -p tavolo.scopa
+uv run mypy -p tavolo.scopa
 ```
 
 `test_engine.py` covers the pure rules; `test_plugin.py` covers the

server/packages/tavolo-scopone/README.md

@@ -31,8 +31,8 @@ application composition root.
 ## Development (from `server/`)
 
 ```sh
-.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
+uv run python -m unittest discover -s packages/tavolo-scopone/tests
-.venv/bin/python -m mypy -p tavolo.scopone
+uv run mypy -p tavolo.scopone
 ```
 
 `test_engine.py` covers the pure rules; `test_plugin.py` covers the

server/pyproject.toml

@@ -1,11 +1,37 @@
-# NOTE: the tavolo-app distribution lives in packages/tavolo-app/ (same
+# NOTE: the five tavolo distributions live in packages/ (same kaya-style
-# kaya-style layout as tavolo-platform and tavolo-scopone). This file
+# layout as tavolo-platform and tavolo-scopone). This file is the root of
-# exists only for tooling that reads configuration from the working
+# the uv workspace and also holds tooling configuration that is read from
-# directory:
+# the working directory:
+# - uv locks and syncs the whole workspace from here;
 # - aerich reads [tool.aerich] from here (server/ locally, /app in the
 #   db-migrate compose service), next to ./migrations;
 # - mypy reads [tool.mypy] from here when run from server/.
 # See the Migrations section in README.md.
+
+[tool.uv]
+# The old pip-compile setup used --index-url for the private Gitea index
+# plus --extra-index-url for PyPI, so the best version across both indexes
+# won. Match that behavior with uv.
+index-strategy = "unsafe-best-match"
+
+[[tool.uv.index]]
+name = "gitea"
+url = "https://gitea.woggioni.net/api/packages/woggioni/pypi/simple"
+default = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple"
+
+[tool.uv.workspace]
+members = ["packages/*"]
+
+[tool.uv.sources]
+tavolo-platform = { workspace = true }
+tavolo-scopone = { workspace = true }
+tavolo-scopa = { workspace = true }
+tavolo-briscola = { workspace = true }
+
 [tool.aerich]
 tortoise_orm = "tavolo.aerich_config.TORTOISE_ORM"
 location = "./migrations"

server/requirements.txt

@@ -1,184 +0,0 @@
-#
-# This file is autogenerated by pip-compile with Python 3.14
-# by the following command (run from server/packages/tavolo-app/):
-#
-#    pip-compile --allow-unsafe --extra otel --extra-index-url=https://pypi.org/simple --index-url=https://gitea.woggioni.net/api/packages/woggioni/pypi/simple --output-file=../../requirements.txt pyproject.toml
-#
-# NOTE: the tavolo-platform, tavolo-scopone, tavolo-scopa, tavolo-briscola
-# and tavolo-app sibling packages are NOT pinned here: they are installed
-# from ./packages in
-# the Dockerfile and in development (pip install -e ./packages/tavolo-platform
-# -e ./packages/tavolo-scopone -e ./packages/tavolo-scopa
-# -e ./packages/tavolo-briscola
-# -e ./packages/tavolo-app). All of their
-# third-party dependencies are direct dependencies of tavolo-app, so this
-# lock covers the full closure. The otel extra (kaya-otel and its
-# OpenTelemetry dependencies) IS included, so OTEL_ENABLED works in the
-# Docker image; pip-compile cannot resolve the unpublishable sibling
-# packages, so regeneration drops them from a copy of the input file (the
-# existing pins constrain the rest).
-#
---index-url https://gitea.woggioni.net/api/packages/woggioni/pypi/simple
---extra-index-url https://pypi.org/simple
-
-aerich==0.10.1
-    # via tavolo-app (pyproject.toml)
-aiosqlite==0.22.1
-    # via tortoise-orm
-anyio==4.15.1
-    # via
-    #   aerich
-    #   httpx
-    #   tortoise-orm
-asyncclick==8.4.2.1
-    # via aerich
-asyncpg==0.31.0
-    # via tavolo-app (pyproject.toml)
-certifi==2026.7.22
-    # via
-    #   httpcore
-    #   httpx
-cffi==2.1.1
-    # via cryptography
-click==8.5.0
-    # via granian
-cryptography==50.0.1
-    # via pyjwt
-dictdiffer==0.10.0
-    # via aerich
-googleapis-common-protos==1.75.4
-    # via opentelemetry-exporter-otlp-proto-http
-granian==2.8.3
-    # via
-    #   kaya-rsgi
-    #   tavolo-app (pyproject.toml)
-h11==0.16.0
-    # via httpcore
-httpcore==1.0.9
-    # via httpx
-httpx==0.28.1
-    # via
-    #   kaya-oidc
-    #   tavolo-app (pyproject.toml)
-idna==3.20
-    # via
-    #   anyio
-    #   httpx
-iso8601==2.1.0
-    # via tortoise-orm
-kaya-core==0.0.7
-    # via
-    #   kaya-cors
-    #   kaya-oidc
-    #   kaya-openapi
-    #   kaya-otel
-    #   kaya-rsgi
-    #   kaya-session
-    #   tavolo-app (pyproject.toml)
-kaya-cors==0.0.7
-    # via tavolo-app (pyproject.toml)
-kaya-oidc==0.0.7
-    # via tavolo-app (pyproject.toml)
-kaya-openapi==0.0.8
-    # via tavolo-app (pyproject.toml)
-kaya-otel==0.0.7
-    # via tavolo-app (pyproject.toml)
-kaya-rsgi==0.0.7
-    # via tavolo-app (pyproject.toml)
-kaya-session==0.0.7
-    # via
-    #   kaya-oidc
-    #   kaya-session-redis
-    #   tavolo-app (pyproject.toml)
-kaya-session-redis==0.0.7
-    # via tavolo-app (pyproject.toml)
-opentelemetry-api==1.45.0
-    # via
-    #   opentelemetry-exporter-http-transport
-    #   opentelemetry-exporter-otlp-proto-http
-    #   opentelemetry-instrumentation
-    #   opentelemetry-instrumentation-asyncpg
-    #   opentelemetry-instrumentation-redis
-    #   opentelemetry-instrumentation-system-metrics
-    #   opentelemetry-sdk
-    #   opentelemetry-semantic-conventions
-opentelemetry-exporter-http-transport[urllib3]==0.66b0
-    # via opentelemetry-exporter-otlp-proto-http
-opentelemetry-exporter-otlp-common==0.66b0
-    # via opentelemetry-exporter-otlp-proto-http
-opentelemetry-exporter-otlp-proto-common==1.45.0
-    # via opentelemetry-exporter-otlp-proto-http
-opentelemetry-exporter-otlp-proto-http==1.45.0
-    # via kaya-otel
-opentelemetry-instrumentation==0.66b0
-    # via
-    #   opentelemetry-instrumentation-asyncpg
-    #   opentelemetry-instrumentation-redis
-    #   opentelemetry-instrumentation-system-metrics
-opentelemetry-instrumentation-asyncpg==0.66b0
-    # via tavolo-app (pyproject.toml)
-opentelemetry-instrumentation-redis==0.66b0
-    # via tavolo-app (pyproject.toml)
-opentelemetry-instrumentation-system-metrics==0.66b0
-    # via tavolo-app (pyproject.toml)
-opentelemetry-proto==1.45.0
-    # via
-    #   opentelemetry-exporter-otlp-proto-common
-    #   opentelemetry-exporter-otlp-proto-http
-opentelemetry-sdk==1.45.0
-    # via
-    #   kaya-otel
-    #   opentelemetry-exporter-otlp-common
-    #   opentelemetry-exporter-otlp-proto-http
-opentelemetry-semantic-conventions==0.66b0
-    # via
-    #   opentelemetry-instrumentation
-    #   opentelemetry-instrumentation-asyncpg
-    #   opentelemetry-instrumentation-redis
-    #   opentelemetry-instrumentation-system-metrics
-    #   opentelemetry-sdk
-packaging==26.3
-    # via opentelemetry-instrumentation
-protobuf==7.36.2
-    # via
-    #   googleapis-common-protos
-    #   opentelemetry-proto
-psutil==7.2.2
-    # via opentelemetry-instrumentation-system-metrics
-pwo==0.1.2
-    # via
-    #   kaya-core
-    #   kaya-rsgi
-    #   kaya-session
-    #   tavolo-app (pyproject.toml)
-pycparser==3.0
-    # via cffi
-pyjwt[crypto]==2.15.1
-    # via
-    #   kaya-oidc
-    #   tavolo-app (pyproject.toml)
-pypika-tortoise==0.6.5
-    # via tortoise-orm
-pyyaml==6.0.3
-    # via tavolo-app (pyproject.toml)
-redis==8.1.0
-    # via
-    #   kaya-session-redis
-    #   tavolo-app (pyproject.toml)
-tortoise-orm==1.1.8
-    # via aerich
-typing-extensions==4.16.0
-    # via
-    #   anyio
-    #   kaya-core
-    #   opentelemetry-api
-    #   opentelemetry-exporter-otlp-proto-http
-    #   opentelemetry-sdk
-    #   opentelemetry-semantic-conventions
-    #   pwo
-urllib3==2.8.0
-    # via opentelemetry-exporter-http-transport
-wrapt==2.5.0
-    # via
-    #   opentelemetry-instrumentation
-    #   opentelemetry-instrumentation-redis