diff --git a/.env.example b/.env.example
index 93e986e..a77f257 100644
--- a/.env.example
+++ b/.env.example
@@ -60,3 +60,11 @@ ENABLE_API_DOCS=false
# restoring a backup: nothing opens a round until you resume from /admin. See
# docs/operativita.md (OPS-27).
START_PAUSED=false
+
+# --- Django site (ADR-54, WEB-07) ---
+# At least 50 characters; the web process refuses to start otherwise. Generate one with:
+# python -c "import secrets; print(secrets.token_urlsafe(64))"
+DJANGO_SECRET_KEY=
+# Optional extras when serving a domain; SITE_ADDRESS itself is always allowed.
+DJANGO_ALLOWED_HOSTS=
+DJANGO_CSRF_TRUSTED_ORIGINS=
diff --git a/.gitignore b/.gitignore
index 0e60b8e..addc729 100644
--- a/.gitignore
+++ b/.gitignore
@@ -12,3 +12,4 @@ secrets/
# graphify and similar tool output
*-out/
+staticfiles/
diff --git a/CLAUDE.md b/CLAUDE.md
index 3e99bc3..d7224d3 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,7 +8,7 @@ The user communicates in Italian in chat — reply to them in Italian. Everythin
## Project status
-All 10 stages of the original build order are code-complete and unit-tested — 758 tests, all under `tests/unit/` (`tests/integration/` is an empty package). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
+All 10 stages of the original build order are code-complete and unit-tested — 775 tests, the old stack's under `tests/unit/` and the Django ones under `tests/django/` (`tests/integration/` is an empty package). Beyond them: Docker + Caddy deployment, admin dashboard (`/admin`), static test UI (`/`), pending-inclusive balance display, an SSE push channel layered over the original polling, self-service password change + admin password reset, and the reconciliation/corroboration machinery below.
Verified on mainnet with real money: registration + address derivation, deposit crediting (at the time, 1-conf; deposits now need `deposit_confirmations`), a real 10 PLM bet (broadcast → confirmed → change credited back), and one full round cycle (close → draw on a real block hash → 70/30 payout with sat math checked against the broadcast tx → confirmation → close → next round auto-opened). **Withdrawal and the RBF bump path have never been exercised against a live broadcast** — unit-tested only.
@@ -34,6 +34,18 @@ Human-facing guides are in [docs/](docs/), in Italian by explicit request (an ex
| Accepted limits | [docs/limiti-noti.md](docs/limiti-noti.md) |
| Fix order for open B-nn | [docs/piano-correzioni.md](docs/piano-correzioni.md) |
+## Django migration in progress (branch `django-migration`)
+
+The repo is being moved from FastAPI to Django — plan in [roadmap.md](roadmap.md), decisions in ADR-54…60, requirements in [docs/sito-e-app.md](docs/sito-e-app.md) (`WEB`). Until roadmap D1 removes it, the sections below describe the **old FastAPI stack**: its code (`app/`) and its `tests/unit/` suite stay in the repo and must keep passing, but it is **no longer part of `docker-compose.yml` or the Docker image**.
+
+New layout: `config/` (settings, urls, wsgi), `apps/accounts` (custom `User`), `apps/lottery` (round engine and the `run_worker` command), `apps/web` (public site and player app), `apps/ops` (staff console), tests in `tests/django/` (settings `config.settings_test`, pytest-django). The stack is `web` (gunicorn) + `worker` (`manage.py run_worker`) + `caddy` on one SQLite file in WAL mode (ADR-55); it needs `DJANGO_SECRET_KEY` in `.env` (≥ 50 chars) and serves `https://localhost` with no domain (WEB-07).
+
+```bash
+DJANGO_DEBUG=true python manage.py runserver # quick local run, no Docker (http://localhost:8000)
+python manage.py makemigrations # after editing a Django model; tests fail if one is missing
+python -m pytest # old suite + tests/django together
+```
+
## Commands
The server always runs via Docker, in dev and prod alike — there is no supported way to run `uvicorn` directly. The venv (`.venv/`) is only for local tooling: tests, Alembic migrations, and the one-time key/secret scripts.
@@ -49,7 +61,7 @@ PYTHONPATH=. python scripts/decrypt_master_key.py # ops recovery: decrypt+pr
PYTHONPATH=. python scripts/encrypt_master_key.py # ops bootstrap: import an externally-generated xprv (--overwrite to replace)
PYTHONPATH=. python scripts/electrum_smoke_test.py # manual check: connect, handshake, subscribe to headers, print the tip
-python -m pytest # all 758 tests
+python -m pytest # all 775 tests
python -m pytest tests/unit/test_hd.py # one file
python -m pytest tests/unit/test_hd.py::test_derivation_is_deterministic # one test
```
diff --git a/Caddyfile b/Caddyfile
index 25ddc19..15ba9e0 100644
--- a/Caddyfile
+++ b/Caddyfile
@@ -6,21 +6,12 @@
# instead, via its internal CA. Browsers will still warn on first visit
# unless that CA is explicitly trusted — expected for local/dev use.
{$SITE_ADDRESS:localhost} {
- # gzip buffers output, which would delay delivery on the SSE stream
- # (/rounds/stream, app/api/routes/rounds.py) — it needs each event flushed
- # to the client immediately, not batched. Everything else still compresses.
- @not_sse {
- not path /rounds/stream
- }
- encode @not_sse gzip
+ encode gzip
- # B-43: Caddy adds none of these on its own. The JWT lives in
- # localStorage, so any XSS exfiltrates it — CSP is the main mitigation.
- # script-src/style-src need 'unsafe-inline' because both SPAs
- # (app/static/index.html, admin.html) use inline onclick handlers and
- # style="" attributes throughout; removing those is a separate,
- # larger refactor, not a header change. fonts.googleapis.com/gstatic.com
- # are the one external asset (the Google Fonts @import in style.css/admin.css).
+ # B-43: Caddy adds none of these on its own. The session cookie is HttpOnly, but a CSP is
+ # still the main mitigation against injected script. 'unsafe-inline' stays for now because
+ # Django Admin uses inline scripts and styles; the pages of the new site (roadmap A5-A8)
+ # are written without them so the policy can be tightened for them later.
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
@@ -35,9 +26,8 @@
# registration throttles of B-33, the SSE per-IP subscriber cap of B-38) is
# defeated by simply rotating a fake value per request. Overwriting the header
# with the actual peer makes the app's assumption true at the source; it also
- # reads the last hop rather than the first (app/api/client_ip.py), so the two
- # defences hold independently.
- reverse_proxy app:8123 {
+ # reads the last hop rather than the first, so the two defences hold independently.
+ reverse_proxy web:8000 {
header_up X-Forwarded-For {remote_host}
}
}
diff --git a/Dockerfile b/Dockerfile
index 71f0ed1..61f02c3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -9,17 +9,19 @@ WORKDIR /app
COPY requirements.lock ./
RUN pip install --no-cache-dir --require-hashes --no-deps -r requirements.lock
-COPY pyproject.toml ./
-COPY app ./app
-COPY migrations ./migrations
-COPY alembic.ini ./
-COPY scripts ./scripts
+# ADR-54: the Django project (`config/`, `apps/`). The previous FastAPI code (`app/`) is no longer
+# part of the image; it stays in the repository until the old backend is removed (roadmap D1).
+COPY pyproject.toml manage.py ./
+COPY config ./config
+COPY apps ./apps
RUN pip install --no-cache-dir --no-deps . \
+ && DJANGO_DEBUG=true python manage.py collectstatic --noinput \
&& useradd --uid 1000 --no-create-home --shell /usr/sbin/nologin app
USER 1000:1000
-EXPOSE 8123
+EXPOSE 8000
-# umask 077: the database, its WAL files and the logs are created readable by the app user only.
-CMD ["/bin/sh", "-c", "umask 077; test -f \"$MASTER_KEY_PATH\" || { echo \"ERROR: master key not found at $MASTER_KEY_PATH -- run: docker compose run --rm app python scripts/generate_master_key.py\" >&2; exit 1; }; alembic upgrade head && exec uvicorn app.main:app --host 0.0.0.0 --port 8123 --proxy-headers --forwarded-allow-ips \"${FORWARDED_ALLOW_IPS:-127.0.0.1}\""]
+# umask 077: the database and its WAL files are created readable by the app user only.
+# The worker service overrides this command (`python manage.py run_worker`).
+CMD ["/bin/sh", "-c", "umask 077; python manage.py migrate --noinput && exec gunicorn config.wsgi --bind 0.0.0.0:8000 --workers 2 --access-logfile - --forwarded-allow-ips \"${FORWARDED_ALLOW_IPS:-127.0.0.1}\""]
diff --git a/README.md b/README.md
index 47e8757..e1b7bc7 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ python -m pytest # all tests
python -m pytest tests/unit/test_hd.py # one file
```
-758 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
+775 unit tests cover HD derivation, PSBT building, the Electrum client, bets,
deposits, withdrawals, the round/draw engine, RBF fee-bumping, admin config,
the pending-inclusive balance calculation, and the SSE push channel. No
automated integration tests against a live Electrum connection — mainnet
diff --git a/apps/__init__.py b/apps/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/accounts/__init__.py b/apps/accounts/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/accounts/admin.py b/apps/accounts/admin.py
new file mode 100644
index 0000000..6d53b53
--- /dev/null
+++ b/apps/accounts/admin.py
@@ -0,0 +1,6 @@
+from django.contrib import admin
+from django.contrib.auth.admin import UserAdmin
+
+from .models import User
+
+admin.site.register(User, UserAdmin)
diff --git a/apps/accounts/apps.py b/apps/accounts/apps.py
new file mode 100644
index 0000000..f7da1e8
--- /dev/null
+++ b/apps/accounts/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class AccountsConfig(AppConfig):
+ name = "apps.accounts"
+ label = "accounts"
diff --git a/apps/accounts/migrations/0001_initial.py b/apps/accounts/migrations/0001_initial.py
new file mode 100644
index 0000000..b7c385c
--- /dev/null
+++ b/apps/accounts/migrations/0001_initial.py
@@ -0,0 +1,43 @@
+# Generated by Django 5.2.19 on 2026-11-16 10:51
+
+import django.contrib.auth.models
+import django.contrib.auth.validators
+import django.db.models.functions.text
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+ initial = True
+
+ dependencies = [
+ ('auth', '0012_alter_user_first_name_max_length'),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name='User',
+ fields=[
+ ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+ ('password', models.CharField(max_length=128, verbose_name='password')),
+ ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')),
+ ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')),
+ ('username', models.CharField(error_messages={'unique': 'A user with that username already exists.'}, help_text='Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.', max_length=150, unique=True, validators=[django.contrib.auth.validators.UnicodeUsernameValidator()], verbose_name='username')),
+ ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')),
+ ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')),
+ ('email', models.EmailField(blank=True, max_length=254, verbose_name='email address')),
+ ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff status')),
+ ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')),
+ ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')),
+ ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.group', verbose_name='groups')),
+ ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.permission', verbose_name='user permissions')),
+ ],
+ options={
+ 'constraints': [models.UniqueConstraint(django.db.models.functions.text.Lower('username'), name='accounts_user_username_ci_unique')],
+ },
+ managers=[
+ ('objects', django.contrib.auth.models.UserManager()),
+ ],
+ ),
+ ]
diff --git a/apps/accounts/migrations/__init__.py b/apps/accounts/migrations/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/accounts/models.py b/apps/accounts/models.py
new file mode 100644
index 0000000..8dc6041
--- /dev/null
+++ b/apps/accounts/models.py
@@ -0,0 +1,16 @@
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+from django.db.models.functions import Lower
+
+
+class User(AbstractUser):
+ """Players and staff share one account model (ADR-54, ADR-56).
+
+ Staff is a role (`is_staff` plus explicit permissions), not a separate table.
+ """
+
+ class Meta:
+ constraints = [
+ # ADR-38: one case-insensitive namespace. The name is stored as typed.
+ models.UniqueConstraint(Lower("username"), name="accounts_user_username_ci_unique"),
+ ]
diff --git a/apps/lottery/__init__.py b/apps/lottery/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/lottery/apps.py b/apps/lottery/apps.py
new file mode 100644
index 0000000..a3b8021
--- /dev/null
+++ b/apps/lottery/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class LotteryConfig(AppConfig):
+ name = "apps.lottery"
+ label = "lottery"
diff --git a/apps/lottery/management/__init__.py b/apps/lottery/management/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/lottery/management/commands/__init__.py b/apps/lottery/management/commands/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/lottery/management/commands/run_worker.py b/apps/lottery/management/commands/run_worker.py
new file mode 100644
index 0000000..cd6db60
--- /dev/null
+++ b/apps/lottery/management/commands/run_worker.py
@@ -0,0 +1,39 @@
+"""The background worker process (ADR-55).
+
+A1 ships the process shell only: it starts, logs, stops cleanly on SIGTERM and shows up as a
+compose service. The round scheduler (A4) and the chain tasks (Phase B) plug into `tick`.
+"""
+
+import logging
+import signal
+import threading
+
+from django.core.management.base import BaseCommand
+
+logger = logging.getLogger(__name__)
+
+TICK_SECONDS = 5
+
+
+def tick() -> None:
+ """One pass over everything the worker is responsible for. Empty until A4."""
+
+
+class Command(BaseCommand):
+ help = "Run the background worker (round scheduler and chain tasks)."
+
+ def add_arguments(self, parser):
+ parser.add_argument("--once", action="store_true", help="Run a single tick and exit.")
+
+ def handle(self, *args, **options):
+ stop = threading.Event()
+ for signum in (signal.SIGTERM, signal.SIGINT):
+ signal.signal(signum, lambda *_: stop.set())
+
+ logger.info("worker started")
+ while not stop.is_set():
+ tick()
+ if options["once"]:
+ break
+ stop.wait(TICK_SECONDS)
+ logger.info("worker stopped")
diff --git a/apps/ops/__init__.py b/apps/ops/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/ops/apps.py b/apps/ops/apps.py
new file mode 100644
index 0000000..1da5542
--- /dev/null
+++ b/apps/ops/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class OpsConfig(AppConfig):
+ name = "apps.ops"
+ label = "ops"
diff --git a/apps/web/__init__.py b/apps/web/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/apps/web/apps.py b/apps/web/apps.py
new file mode 100644
index 0000000..6ced256
--- /dev/null
+++ b/apps/web/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class WebConfig(AppConfig):
+ name = "apps.web"
+ label = "web"
diff --git a/apps/web/templates/web/home.html b/apps/web/templates/web/home.html
new file mode 100644
index 0000000..4fe5816
--- /dev/null
+++ b/apps/web/templates/web/home.html
@@ -0,0 +1,14 @@
+
+
+
+
+
+ PLM Lottery
+
+
+
+ PLM Lottery
+ Il sito è in costruzione.
+
+
+
diff --git a/apps/web/urls.py b/apps/web/urls.py
new file mode 100644
index 0000000..90f2092
--- /dev/null
+++ b/apps/web/urls.py
@@ -0,0 +1,9 @@
+from django.urls import path
+
+from . import views
+
+app_name = "web"
+urlpatterns = [
+ path("", views.home, name="home"),
+ path("health/live", views.health_live, name="health-live"),
+]
diff --git a/apps/web/views.py b/apps/web/views.py
new file mode 100644
index 0000000..c1b4790
--- /dev/null
+++ b/apps/web/views.py
@@ -0,0 +1,18 @@
+from django.db import connection
+from django.http import HttpResponse, JsonResponse
+from django.shortcuts import render
+
+
+def home(request):
+ """Placeholder landing page: the real home (WEB-10) arrives with A6."""
+ return render(request, "web/home.html")
+
+
+def health_live(request):
+ """Liveness for the container healthcheck: the process answers and the database opens (ARC-73)."""
+ try:
+ with connection.cursor() as cursor:
+ cursor.execute("SELECT 1")
+ except Exception:
+ return HttpResponse("database unavailable", status=503, content_type="text/plain")
+ return JsonResponse({"status": "ok"})
diff --git a/config/__init__.py b/config/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/config/settings.py b/config/settings.py
new file mode 100644
index 0000000..a82dd65
--- /dev/null
+++ b/config/settings.py
@@ -0,0 +1,145 @@
+"""Django settings (ADR-54, ADR-55, WEB-07).
+
+Everything environment-specific comes from environment variables, so the same image
+serves `http://localhost` today and a real domain later with configuration only.
+"""
+
+import os
+from pathlib import Path
+
+from django.core.exceptions import ImproperlyConfigured
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+
+
+def _env_list(name: str) -> list[str]:
+ return [item.strip() for item in os.environ.get(name, "").split(",") if item.strip()]
+
+
+DEBUG = os.environ.get("DJANGO_DEBUG", "false").lower() == "true"
+
+# Like ADR-11 for the old server: refuse to start with an inadequate secret instead of
+# running with a guessable one. DEBUG (local development without Docker) is exempt.
+SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "")
+if not DEBUG and len(SECRET_KEY) < 50:
+ raise ImproperlyConfigured(
+ "DJANGO_SECRET_KEY must be at least 50 characters. Generate one with: "
+ "python -c \"import secrets; print(secrets.token_urlsafe(64))\""
+ )
+if DEBUG and not SECRET_KEY:
+ SECRET_KEY = "insecure-development-key-" + "x" * 40
+
+# WEB-07: `localhost` works out of the box; a domain is added by configuration only.
+SITE_ADDRESS = os.environ.get("SITE_ADDRESS", "localhost")
+ALLOWED_HOSTS = sorted({"localhost", "127.0.0.1", "[::1]", "web", SITE_ADDRESS, *_env_list("DJANGO_ALLOWED_HOSTS")})
+CSRF_TRUSTED_ORIGINS = sorted(
+ {f"https://{SITE_ADDRESS}", *_env_list("DJANGO_CSRF_TRUSTED_ORIGINS")}
+)
+
+INSTALLED_APPS = [
+ "django.contrib.admin",
+ "django.contrib.auth",
+ "django.contrib.contenttypes",
+ "django.contrib.sessions",
+ "django.contrib.messages",
+ "django.contrib.staticfiles",
+ "apps.accounts",
+ "apps.lottery",
+ "apps.web",
+ "apps.ops",
+]
+
+MIDDLEWARE = [
+ "django.middleware.security.SecurityMiddleware",
+ "whitenoise.middleware.WhiteNoiseMiddleware",
+ "django.contrib.sessions.middleware.SessionMiddleware",
+ "django.middleware.common.CommonMiddleware",
+ "django.middleware.csrf.CsrfViewMiddleware",
+ "django.contrib.auth.middleware.AuthenticationMiddleware",
+ "django.contrib.messages.middleware.MessageMiddleware",
+ "django.middleware.clickjacking.XFrameOptionsMiddleware",
+]
+
+ROOT_URLCONF = "config.urls"
+WSGI_APPLICATION = "config.wsgi.application"
+
+TEMPLATES = [
+ {
+ "BACKEND": "django.template.backends.django.DjangoTemplates",
+ "DIRS": [],
+ "APP_DIRS": True,
+ "OPTIONS": {
+ "context_processors": [
+ "django.template.context_processors.request",
+ "django.contrib.auth.context_processors.auth",
+ "django.contrib.messages.context_processors.messages",
+ ],
+ },
+ },
+]
+
+# ADR-55: one SQLite file in WAL mode shared by the web and the worker processes. Every write
+# transaction takes the write lock up front (`BEGIN IMMEDIATE`), so two processes never deadlock
+# upgrading a read lock, and durability matches the old server (`synchronous=FULL`).
+DATABASES = {
+ "default": {
+ "ENGINE": "django.db.backends.sqlite3",
+ "NAME": os.environ.get("DJANGO_DB_PATH", str(BASE_DIR / "data" / "db" / "site.sqlite3")),
+ "OPTIONS": {
+ "transaction_mode": "IMMEDIATE",
+ "timeout": 20,
+ "init_command": "PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON;",
+ },
+ }
+}
+DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"
+
+# The model is defined before the first migration (ADR-54): changing it later is painful.
+AUTH_USER_MODEL = "accounts.User"
+
+# Argon2 first, as in ADR-36; the others only keep Django's own tooling working.
+PASSWORD_HASHERS = [
+ "django.contrib.auth.hashers.Argon2PasswordHasher",
+ "django.contrib.auth.hashers.PBKDF2PasswordHasher",
+]
+AUTH_PASSWORD_VALIDATORS = [
+ {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator", "OPTIONS": {"min_length": 8}},
+ {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
+ {"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
+]
+
+# ADR-60: Italian only for the pilot; gettext is on so other languages can be added later.
+LANGUAGE_CODE = "it"
+TIME_ZONE = "UTC"
+USE_I18N = True
+USE_TZ = True
+
+STATIC_URL = "/static/"
+STATIC_ROOT = BASE_DIR / "staticfiles"
+STORAGES = {
+ "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
+ "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"},
+}
+
+# Caddy terminates TLS (even for localhost) and tells us so (WEB-02, WEB-07). Secure cookies
+# apply wherever there is HTTPS: that is every Docker run, and not `runserver` in DEBUG.
+SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
+SESSION_COOKIE_SECURE = not DEBUG
+CSRF_COOKIE_SECURE = not DEBUG
+SESSION_COOKIE_HTTPONLY = True
+SESSION_COOKIE_SAMESITE = "Lax"
+CSRF_COOKIE_SAMESITE = "Lax"
+SECURE_CONTENT_TYPE_NOSNIFF = True
+X_FRAME_OPTIONS = "DENY"
+SECURE_REFERRER_POLICY = "strict-origin-when-cross-origin"
+
+LOGIN_URL = "/accedi/"
+LOGIN_REDIRECT_URL = "/app/"
+LOGOUT_REDIRECT_URL = "/"
+
+LOGGING = {
+ "version": 1,
+ "disable_existing_loggers": False,
+ "handlers": {"console": {"class": "logging.StreamHandler"}},
+ "root": {"handlers": ["console"], "level": os.environ.get("LOG_LEVEL", "INFO")},
+}
diff --git a/config/settings_test.py b/config/settings_test.py
new file mode 100644
index 0000000..b8506d1
--- /dev/null
+++ b/config/settings_test.py
@@ -0,0 +1,15 @@
+"""Settings for the test suite: a throw-away secret and an in-memory database."""
+
+import os
+
+os.environ.setdefault("DJANGO_SECRET_KEY", "test-secret-" + "x" * 60)
+
+from .settings import * # noqa: E402,F401,F403
+
+# A fast hasher: the tests create many users, and Argon2 is slow on purpose.
+PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]
+STORAGES = {
+ "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
+ "staticfiles": {"BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage"},
+}
+MIDDLEWARE = [m for m in MIDDLEWARE if "whitenoise" not in m] # no collected static files in tests
diff --git a/config/urls.py b/config/urls.py
new file mode 100644
index 0000000..33cdcca
--- /dev/null
+++ b/config/urls.py
@@ -0,0 +1,7 @@
+from django.contrib import admin
+from django.urls import include, path
+
+urlpatterns = [
+ path("admin/", admin.site.urls),
+ path("", include("apps.web.urls")),
+]
diff --git a/config/wsgi.py b/config/wsgi.py
new file mode 100644
index 0000000..ccf67ba
--- /dev/null
+++ b/config/wsgi.py
@@ -0,0 +1,6 @@
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+application = get_wsgi_application()
diff --git a/docker-compose.yml b/docker-compose.yml
index b08f5ce..255dd3e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,52 +1,65 @@
+# ADR-54, ADR-55, WEB-07: the same file serves http://localhost today and a domain later —
+# only SITE_ADDRESS (and DJANGO_ALLOWED_HOSTS / DJANGO_CSRF_TRUSTED_ORIGINS if needed) change.
+# The previous FastAPI service is not part of the stack any more (roadmap D1 removes the code).
services:
# B-91 (SEC-51): one-shot, as root, so the bind-mounted ./data belongs to the non-root
# user the app runs as (uid 1000) and is closed to everyone else — also the first time
# after an older root-owned install, with no sudo on the host.
data-permissions:
build: .
- image: plm-lottery-app:local
+ image: plm-lottery-web:local
user: "0:0"
entrypoint: ["/bin/sh", "-c", "chown -R 1000:1000 /data && chmod -R go-rwx /data"]
volumes:
- ./data:/data
restart: "no"
- app:
+ # The web process: Django behind gunicorn. It applies the migrations at startup.
+ web:
build: .
- image: plm-lottery-app:local
+ image: plm-lottery-web:local
restart: unless-stopped
env_file: .env
environment:
- - DATABASE_URL=sqlite+aiosqlite:////app/db_data/plm_lottery.db
- - MASTER_KEY_PATH=/app/key_data/master.xprv.enc
- - XPRV_ENCRYPTION_KEY_FILE=/run/secrets/xprv_encryption_key
- # B-92 (ARC-02): uvicorn trusts X-Forwarded-For from Caddy's fixed address only, so the access
- # log records the client's IP instead of Caddy's.
+ - DJANGO_DB_PATH=/app/db_data/site.sqlite3
+ - SITE_ADDRESS=${SITE_ADDRESS:-localhost}
+ # gunicorn trusts X-Forwarded-Proto/For from Caddy's fixed address only (ARC-02).
- FORWARDED_ALLOW_IPS=172.28.0.10
- secrets:
- - xprv_encryption_key
volumes:
- ./data/db:/app/db_data
- - ./data/keys:/app/key_data
- - ./data/logs:/app/logs
expose:
- - "8123"
- # B-92 (ARC-61): ready = Electrum connected, a recent header, a live scheduler. Docker does not
- # restart an unhealthy container (the process exiting does); the state is for monitoring.
+ - "8000"
+ # ARC-73: liveness = the process answers and the database opens.
healthcheck:
test:
- CMD
- python
- -c
- - "import urllib.request as u; u.urlopen('http://127.0.0.1:8123/health/ready', timeout=4)"
+ - "import urllib.request as u; u.urlopen('http://127.0.0.1:8000/health/live', timeout=4)"
interval: 30s
timeout: 5s
retries: 3
- start_period: 60s
+ start_period: 30s
depends_on:
data-permissions:
condition: service_completed_successfully
+ # The background worker (ADR-55): its own process on the same SQLite file. It starts after
+ # the web process has migrated the database.
+ worker:
+ build: .
+ image: plm-lottery-web:local
+ restart: unless-stopped
+ env_file: .env
+ environment:
+ - DJANGO_DB_PATH=/app/db_data/site.sqlite3
+ command: ["/bin/sh", "-c", "umask 077; exec python manage.py run_worker"]
+ volumes:
+ - ./data/db:/app/db_data
+ depends_on:
+ web:
+ condition: service_healthy
+
caddy:
image: caddy:2-alpine@sha256:d8542f48d34a9cf4e4c11a478865229840e87e4c96ea3f439101f31a5d35f75f
restart: unless-stopped
@@ -63,20 +76,16 @@ services:
default:
ipv4_address: 172.28.0.10
depends_on:
- - app
+ - web
-# A fixed subnet and a fixed address for Caddy, so uvicorn can trust exactly that one proxy (ARC-02).
+# A fixed subnet and a fixed address for Caddy, so gunicorn can trust exactly that one proxy (ARC-02).
networks:
default:
ipam:
config:
- subnet: 172.28.0.0/24
-# The Fernet key that protects the master key lives in its own file, outside ./data (a backup of
-# the data does not carry both) and in no environment variable (SEC-53).
-secrets:
- xprv_encryption_key:
- file: ./secrets/xprv_encryption.key
+# The master-key secret returns with the worker in phase B (roadmap B4): only that process may read it.
volumes:
caddy_data:
diff --git a/docs/architettura.md b/docs/architettura.md
index 47213ba..9022067 100644
--- a/docs/architettura.md
+++ b/docs/architettura.md
@@ -960,3 +960,33 @@ italiano.
*Codice:* `app/rounds/events.py:RoundEventBroadcaster` ·
`app/tx/locks.py:UserLocks` · `app/auth/rate_limit.py:AuthRateLimiters` ·
`app/main.py:lifespan`
+
+## Sito Django (migrazione in corso)
+
+Il nuovo sito sostituisce il backend FastAPI descritto sopra (roadmap A1–D1); finché il vecchio codice
+non è rimosso le sezioni precedenti descrivono lo stato storico. Scelte: [ADR-54](adr/ADR-54-django-unico-framework-web-tre-aree.md),
+[ADR-55](adr/ADR-55-sqlite-wal-web-worker-processi-separati.md).
+
+- **[ARC-70]** **Database condiviso da due processi.** Il web e il worker usano lo stesso file SQLite in
+ modalità WAL, con `synchronous=FULL`, chiavi esterne attive e ogni transazione di scrittura aperta con
+ `BEGIN IMMEDIATE` (`transaction_mode`); un blocco non ottenuto entro 20 secondi è un errore, mai un'attesa
+ senza fine.
+ *Stato:* implementato (A1) ·
+ *Codice:* `config/settings.py:DATABASES` · *Test:* `tests/django/test_scaffold.py::test_sqlite_pragmas_apply_to_a_file_database`
+- **[ARC-71]** **Il worker è un processo a sé.** `manage.py run_worker` esegue i compiti di fondo a intervalli
+ regolari, si ferma in modo pulito su SIGTERM/SIGINT e, nel compose, parte solo dopo che il web è sano (cioè dopo
+ le migrazioni). Un riavvio del web non ferma il worker e viceversa.
+ *Stato:* implementato come guscio (A1); i compiti arrivano con A4 e la Fase B ·
+ *Codice:* `apps/lottery/management/commands/run_worker.py` · *Test:* `tests/django/test_scaffold.py::test_worker_runs_one_tick_and_exits`
+- **[ARC-72]** **Nessuna coordinazione in memoria fra web e worker.** Esclusione reciproca e unicità si
+ ottengono con vincoli e transazioni del database, mai con blocchi o code in memoria.
+ *Stato:* da implementare (A2 per i vincoli, B6 per la prenotazione degli UTXO).
+- **[ARC-73]** **Liveness.** `GET /health/live` risponde `200 {"status": "ok"}` se il processo risponde e il
+ database si apre, `503` altrimenti; il compose lo usa come healthcheck del servizio `web`.
+ *Stato:* implementato (A1) ·
+ *Codice:* `apps/web/views.py:health_live` · *Test:* `tests/django/test_scaffold.py::test_health_live_checks_the_database`
+- **[ARC-74]** **Segreto obbligatorio.** Il processo rifiuta di partire se `DJANGO_SECRET_KEY` ha meno di 50
+ caratteri (come [ADR-11](adr/ADR-11-server-rifiuta-partire-segreti-inadeguati.md) per il vecchio server);
+ solo `DJANGO_DEBUG=true` (sviluppo senza Docker) ne genera uno non sicuro.
+ *Stato:* implementato (A1) ·
+ *Codice:* `config/settings.py` · *Test:* `tests/django/test_scaffold.py::test_refuses_to_start_without_a_secret`
diff --git a/docs/running-the-server.md b/docs/running-the-server.md
index f000f47..79f06bc 100644
--- a/docs/running-the-server.md
+++ b/docs/running-the-server.md
@@ -1,5 +1,7 @@
# Avviare il server
+> **Nota (migrazione a Django).** Questa guida descrive il vecchio stack FastAPI, non più nel `docker-compose.yml`. L'avvio del nuovo sito è in [sito-e-app.md](sito-e-app.md#6--avvio-in-locale).
+
Presuppone che [setup.md](setup.md) sia già stato completato (`.env` pronto,
master key generata). Le migrazioni del database non si applicano a mano: le
esegue il container a ogni avvio, prima di far partire il server.
diff --git a/docs/setup.md b/docs/setup.md
index 2238957..1cb196a 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1,5 +1,7 @@
# Setup
+> **Nota (migrazione a Django).** Questa guida descrive il vecchio stack FastAPI, non più nel `docker-compose.yml`. L'avvio del nuovo sito è in [sito-e-app.md](sito-e-app.md#6--avvio-in-locale).
+
Passaggi da eseguire una tantum per preparare un'istanza di PLM Lottery, prima di
poterla avviare. Il server gira sempre in Docker; il venv serve solo a test, migrazioni da generare e script una tantum. Per come avviarla poi ogni volta, vedi
[running-the-server.md](running-the-server.md).
diff --git a/docs/sito-e-app.md b/docs/sito-e-app.md
index 953d086..31d295e 100644
--- a/docs/sito-e-app.md
+++ b/docs/sito-e-app.md
@@ -5,8 +5,9 @@ Prefisso: `WEB`. Origine: [../TODO.md](../TODO.md). Scelte: [ADR-54](adr/ADR-54-
(staff), [ADR-57](adr/ADR-57-due-pause-distinte-dopo-round-e-incidente.md) (pause),
[ADR-60](adr/ADR-60-pilota-solo-italiano.md) (lingua).
-Tutti i requisiti di questo documento sono `*Stato:* da implementare`: oggi
-il sito è `index.html` con backend FastAPI (vedi [architettura.md](architettura.md)).
+I requisiti sono `*Stato:* da implementare` salvo dove indicato diversamente; la
+sequenza è in [../roadmap.md](../roadmap.md). Il vecchio sito è `index.html` con
+backend FastAPI (vedi [architettura.md](architettura.md)).
## 1 · Struttura
@@ -26,7 +27,8 @@ il sito è `index.html` con backend FastAPI (vedi [architettura.md](architettura
| `/ops/` | staff | supervisione e azioni operative autorizzate |
| `/admin/` | staff con permessi sui modelli | utenti e segnalazioni; record di gioco in sola lettura |
- *Codice:* da implementare · *Test:* da implementare
+ *Stato:* scheletro (A1): progetto Django, `/` segnaposto, `/admin/` ·
+ *Codice:* `config/urls.py`, `apps/web/urls.py` · *Test:* `tests/django/test_scaffold.py::test_home_answers_on_localhost`
- **[WEB-02]** L'autenticazione usa le sessioni Django; ogni scrittura è
protetta da CSRF e il cookie di sessione ha gli attributi `Secure`,
`HttpOnly` e `SameSite`.
@@ -47,6 +49,9 @@ il sito è `index.html` con backend FastAPI (vedi [architettura.md](architettura
dominio definitivo si aggiunge solo con la configurazione (`SITE_ADDRESS`,
`ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`), senza modifiche al codice, e i
cookie `Secure` valgono solo dove c'è HTTPS ([WEB-02]).
+ *Stato:* implementato (A1) ·
+ *Codice:* `config/settings.py`, `docker-compose.yml`, `Caddyfile` ·
+ *Test:* `tests/django/test_scaffold.py::test_domain_comes_from_configuration_only`, `test_unknown_host_is_refused`
## 2 · Area pubblica
@@ -108,3 +113,19 @@ il sito è `index.html` con backend FastAPI (vedi [architettura.md](architettura
- **[WEB-44]** Ogni comando operativo è negato a un giocatore e a uno staff
senza il permesso specifico, si riflette sul sito con l'effetto previsto e
compare nell'audit.
+
+## 6 · Avvio in locale
+
+Per navigare il sito su `https://localhost` (certificato autofirmato: l'avviso del browser alla prima visita è atteso):
+
+```bash
+mkdir -p data/db
+cp .env.example .env # poi impostare DJANGO_SECRET_KEY (almeno 50 caratteri):
+python3 -c "import secrets; print(secrets.token_urlsafe(64))"
+docker compose up -d --build
+```
+
+Servizi: `web` (Django + gunicorn, applica le migrazioni), `worker` ([ARC-71]) e `caddy`.
+Con un dominio reale basta `SITE_ADDRESS=lottery.example.com docker compose up -d`
+([WEB-07]). Il vecchio `docs/setup.md` e `docs/running-the-server.md` descrivono lo stack
+FastAPI, che non è più nel compose.
diff --git a/manage.py b/manage.py
new file mode 100644
index 0000000..7f082c5
--- /dev/null
+++ b/manage.py
@@ -0,0 +1,14 @@
+#!/usr/bin/env python
+import os
+import sys
+
+
+def main() -> None:
+ os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+ from django.core.management import execute_from_command_line
+
+ execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/pyproject.toml b/pyproject.toml
index dca8bb8..75a2773 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,6 +14,9 @@ dependencies = [
"cryptography>=43.0",
"embit>=0.7",
"qrcode[pil]>=7.4",
+ "Django>=5.2,<5.3",
+ "gunicorn>=23",
+ "whitenoise>=6.7",
]
[project.optional-dependencies]
@@ -21,11 +24,13 @@ dev = [
"pytest>=8.3",
"pytest-asyncio>=0.24",
"httpx>=0.27",
+ "pytest-django>=4.9",
]
[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
+DJANGO_SETTINGS_MODULE = "config.settings_test"
[tool.setuptools.packages.find]
-include = ["app*"]
+include = ["app*", "config*", "apps*"]
diff --git a/requirements.lock b/requirements.lock
index 0412c87..382e6f8 100644
--- a/requirements.lock
+++ b/requirements.lock
@@ -73,6 +73,10 @@ argon2-cffi-bindings==26.1.0 \
--hash=sha256:f9c4420a7a864fe1b86ce35befc95b8e39fb852493b81cf798671ddc265de638 \
--hash=sha256:ffff613aaa9ce6236766e2fc6dc560bb5abde7a2e2416e3db1f9ae395a2b4dd4
# via argon2-cffi
+asgiref==3.13.0 \
+ --hash=sha256:034cc8cbf72d00553b4be256703ac545120b4e50af13b49dec99da899aeeecb4 \
+ --hash=sha256:f9596a2434512686473d50f96ff6207fbba49ae1a785dfac614df4aeb085674d
+ # via django
cffi==2.1.1 \
--hash=sha256:046bfc24911b37851ee1b51aab8bffe713d89c68c6a057b09484ce9fd5f69b4e \
--hash=sha256:06c72bb76605a4b0cd0aad6930b69d4baf7dd5d806cfc409b824191099700e66 \
@@ -242,6 +246,10 @@ cryptography==50.0.2 \
--hash=sha256:fa8f5efb344d6908a1ce62f4a24e2e5780f825d6f53f5f50ec5ffacac72936cb \
--hash=sha256:fdd28f912fccfec1846a94e2e1e8f9b0012f557f0c46fe4f3eb0d7a87afcf90b
# via plm-lottery (pyproject.toml)
+django==5.2.19 \
+ --hash=sha256:5965d974a5218a2b68a11dd1276434707f23886525c23f0598eccedaf4f4ca00 \
+ --hash=sha256:ad03d8abc51dbff95ebf34b27123cf0c26a3b62db7ba0cd520783686362533d1
+ # via plm-lottery (pyproject.toml)
embit==0.8.0 \
--hash=sha256:8bf4b10073c67400370ce523fb16f035fe759f6fdd987c579bdcc268d75ed770
# via plm-lottery (pyproject.toml)
@@ -330,6 +338,10 @@ greenlet==3.5.6 \
--hash=sha256:fe3170a69fe039b18ad18171e66faa9a75f6fe9d78f968fd9b54e09fbd714d81 \
--hash=sha256:fea4427d1ffdb3b523d7daa6712038428a4c16c450b9777bdd1221cfee0eab49
# via sqlalchemy
+gunicorn==27.0.1 \
+ --hash=sha256:378b26b9a38adcf4592f28828233c1716acc55e833ea06bf48719782efaa0d10 \
+ --hash=sha256:b1514965361c8b7e8107a80aa2a92636878df1ccfac6dd204a676426e04d9e3e
+ # via plm-lottery (pyproject.toml)
h11==0.16.0 \
--hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \
--hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86
@@ -1022,6 +1034,10 @@ sqlalchemy==2.1.5 \
# via
# alembic
# plm-lottery (pyproject.toml)
+sqlparse==0.6.1 \
+ --hash=sha256:3be5a72d04c873d690d7c6dedd33d6fae2ef82759881ceec02fc2efd0cba564f \
+ --hash=sha256:ca722573f848ff2d30e40ea30f53a104b7dea7635ea9285891263eb2c58fb6e7
+ # via django
starlette==1.8.0 \
--hash=sha256:1565dc0b35d5737a271ed1e0e04e949f4e81198799f216d2667b0a0fb9cf9522 \
--hash=sha256:dfdd6b29c26483288088d990eee59631dedadd66ce20d203402a7ca8e3c4656f
@@ -1299,3 +1315,7 @@ websockets==17.2 \
--hash=sha256:fb78fb4158c12f77a934a003006784108a27a6553cfc0c6f10483c9c02e94f48 \
--hash=sha256:fcce735ffd72ac4056db05325d9f0232382b74826f0196eb6a15ca903abdaa0f
# via uvicorn
+whitenoise==6.12.0 \
+ --hash=sha256:f723ebb76a112e98816ff80fcea0a6c9b8ecde835f8ddda25df7a30a3c2db6ad \
+ --hash=sha256:fc5e8c572e33ebf24795b47b6a7da8da3c00cff2349f5b04c02f28d0cc5a3cc2
+ # via plm-lottery (pyproject.toml)
diff --git a/roadmap.md b/roadmap.md
index c9560c5..833787f 100644
--- a/roadmap.md
+++ b/roadmap.md
@@ -24,7 +24,7 @@ Il lavoro prosegue in un solo branch, senza convivenza di servizi.
Uscita: un giocatore completa il round dimostrativo in `localhost`, l'operatore lo segue e lo mette in pausa, un visitatore verifica l'esito.
-- [ ] **A1 · Scheletro Django.** Progetto Django 5.2 (`config/`, app `accounts`, `lottery`, `web`, `ops`), modello utente personalizzato prima delle migrazioni, impostazioni da ambiente (`SITE_ADDRESS`, `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`), SQLite WAL con `transaction_mode=IMMEDIATE`, servizi `web` e `worker` nel compose dietro Caddy. *Requisiti:* WEB-01, WEB-07, ARC. *Test:* `manage.py check`, avvio e risposta `200` su `/`.
+- [x] **A1 · Scheletro Django.** Progetto Django 5.2 (`config/`, app `accounts`, `lottery`, `web`, `ops`), modello utente personalizzato prima delle migrazioni, impostazioni da ambiente (`SITE_ADDRESS`, `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`), SQLite WAL con `transaction_mode=IMMEDIATE`, servizi `web` e `worker` nel compose dietro Caddy. *Requisiti:* WEB-01, WEB-07, ARC. *Test:* `manage.py check`, avvio e risposta `200` su `/`.
- [ ] **A2 · Modelli e vincoli.** Account, Round (parametri fotografati all'apertura), Partecipazione, Movimento, Transazione, Audit (solo aggiunta). Importi interi in unità minime; un solo round attivo e una sola puntata per utente e round come vincoli del database. *Requisiti:* WEB-04, DAT. *Test:* violazione di ogni vincolo.
- [ ] **A3 · Ledger simulato.** Interfaccia dei servizi (deposito, puntata, pagamento) con implementazione simulata e **chiave di idempotenza**: un doppio invio produce una sola operazione. *Requisiti:* WEB-23, ADR-59. *Test:* doppio invio, saldo insufficiente, importi al limite.
- [ ] **A4 · Ciclo del round e worker.** Apertura, chiusura, estrazione e pagamento 70/30 nel worker (`manage.py run_worker`), con l'estrazione commit-reveal dello stesso algoritmo del motore. *Requisiti:* RND esistenti riletti sul modello nuovo. *Test:* round completo deterministico, ripresa dopo riavvio del worker.
diff --git a/tests/django/__init__.py b/tests/django/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/django/test_scaffold.py b/tests/django/test_scaffold.py
new file mode 100644
index 0000000..7710569
--- /dev/null
+++ b/tests/django/test_scaffold.py
@@ -0,0 +1,189 @@
+"""A1 — Django skeleton: WEB-01, WEB-07, ARC-70, ARC-73, ADR-54, ADR-55, ADR-38, ADR-11."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.core.management import call_command
+from django.db import IntegrityError, connection, transaction
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def _import_settings(**env: str) -> subprocess.CompletedProcess:
+ """Import `config.settings` in a clean process with exactly the given environment."""
+ clean = {"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), **env}
+ return subprocess.run(
+ [sys.executable, "-c", "import config.settings"],
+ cwd=ROOT, env=clean, capture_output=True, text=True,
+ )
+
+
+# --- WEB-01 / WEB-07: the site answers, on localhost, with no domain configured ---------------
+
+
+def test_home_answers_on_localhost(client):
+ """WEB-07: `http://localhost` serves the placeholder home in Italian."""
+ response = client.get("/", HTTP_HOST="localhost")
+ assert response.status_code == 200
+ assert "PLM Lottery" in response.content.decode()
+ assert 'lang="it"' in response.content.decode()
+
+
+@pytest.mark.django_db
+def test_health_live_checks_the_database(client):
+ """ARC-73: liveness answers 200 and says ok while the database opens."""
+ response = client.get("/health/live", HTTP_HOST="localhost")
+ assert response.status_code == 200
+ assert response.json() == {"status": "ok"}
+
+
+@pytest.mark.django_db
+def test_health_live_reports_a_database_failure(client, monkeypatch):
+ """ARC-73: an unreachable database is a 503, not a 200."""
+ def boom(*args, **kwargs):
+ raise RuntimeError("down")
+ monkeypatch.setattr(connection, "cursor", boom)
+ assert client.get("/health/live", HTTP_HOST="localhost").status_code == 503
+
+
+def test_unknown_host_is_refused(client):
+ """WEB-07: only configured hosts are served; a domain is added by configuration."""
+ assert client.get("/", HTTP_HOST="evil.example").status_code == 400
+
+
+def test_domain_comes_from_configuration_only():
+ """WEB-07: SITE_ADDRESS adds the host and the CSRF origin, with no code change."""
+ code = (
+ "import config.settings as s;"
+ "assert 'lottery.example.com' in s.ALLOWED_HOSTS;"
+ "assert 'https://lottery.example.com' in s.CSRF_TRUSTED_ORIGINS"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", code], cwd=ROOT, capture_output=True, text=True,
+ env={"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT),
+ "DJANGO_SECRET_KEY": "k" * 60, "SITE_ADDRESS": "lottery.example.com"},
+ )
+ assert result.returncode == 0, result.stderr
+
+
+# --- ADR-11 analogue: refuse to start with an inadequate secret --------------------------------
+
+
+def test_refuses_to_start_without_a_secret():
+ result = _import_settings()
+ assert result.returncode != 0
+ assert "DJANGO_SECRET_KEY" in result.stderr
+
+
+def test_refuses_to_start_with_a_short_secret():
+ result = _import_settings(DJANGO_SECRET_KEY="short")
+ assert result.returncode != 0
+
+
+def test_a_long_secret_is_accepted():
+ assert _import_settings(DJANGO_SECRET_KEY="k" * 60).returncode == 0
+
+
+# --- WEB-02: session and CSRF cookie attributes ----------------------------------------------
+
+
+def test_cookies_are_secure_outside_debug():
+ """WEB-02: outside DEBUG the cookies are Secure, HttpOnly and SameSite."""
+ code = (
+ "import config.settings as s;"
+ "assert s.SESSION_COOKIE_SECURE and s.CSRF_COOKIE_SECURE;"
+ "assert s.SESSION_COOKIE_HTTPONLY;"
+ "assert s.SESSION_COOKIE_SAMESITE == 'Lax'"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", code], cwd=ROOT, capture_output=True, text=True,
+ env={"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), "DJANGO_SECRET_KEY": "k" * 60},
+ )
+ assert result.returncode == 0, result.stderr
+
+
+# --- ADR-55: SQLite shared by web and worker --------------------------------------------------
+
+
+def test_sqlite_is_configured_for_two_processes():
+ """ADR-55: IMMEDIATE write transactions, WAL and synchronous=FULL are requested."""
+ options = settings.DATABASES["default"]["OPTIONS"]
+ assert options["transaction_mode"] == "IMMEDIATE"
+ assert "journal_mode=WAL" in options["init_command"]
+ assert "synchronous=FULL" in options["init_command"]
+
+
+def test_sqlite_pragmas_apply_to_a_file_database(tmp_path):
+ """ARC-70: on a file database the pragmas really take effect."""
+ code = (
+ "import django, os;"
+ "os.environ['DJANGO_SETTINGS_MODULE']='config.settings';"
+ "django.setup();"
+ "from django.db import connection;"
+ "c = connection.cursor();"
+ "c.execute('PRAGMA journal_mode'); assert c.fetchone()[0] == 'wal';"
+ "c.execute('PRAGMA synchronous'); assert c.fetchone()[0] == 2;"
+ "c.execute('PRAGMA foreign_keys'); assert c.fetchone()[0] == 1"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", code], cwd=ROOT, capture_output=True, text=True,
+ env={"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), "DJANGO_SECRET_KEY": "k" * 60,
+ "DJANGO_DB_PATH": str(tmp_path / "site.sqlite3")},
+ )
+ assert result.returncode == 0, result.stderr
+
+
+# --- ADR-54 / ADR-38: the user model, case-insensitive usernames ---------------------------------
+
+
+def test_the_custom_user_model_is_in_use():
+ assert settings.AUTH_USER_MODEL == "accounts.User"
+ assert get_user_model()._meta.label == "accounts.User"
+
+
+@pytest.mark.django_db
+def test_usernames_are_unique_ignoring_case():
+ """ADR-38: `Mario` and `mario` are the same name."""
+ User = get_user_model()
+ User.objects.create_user("Mario", password="x" * 12)
+ with pytest.raises(IntegrityError), transaction.atomic():
+ User.objects.create_user("mario", password="x" * 12)
+
+
+@pytest.mark.django_db
+def test_the_username_is_stored_as_typed():
+ User = get_user_model()
+ User.objects.create_user("Mario", password="x" * 12)
+ assert User.objects.get().username == "Mario"
+
+
+def test_passwords_use_argon2_outside_tests():
+ """ADR-36: Argon2 stays the password hash; the test settings only swap it for speed."""
+ code = (
+ "import config.settings as s;"
+ "assert s.PASSWORD_HASHERS[0].endswith('Argon2PasswordHasher')"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", code], cwd=ROOT, capture_output=True, text=True,
+ env={"PATH": os.environ["PATH"], "PYTHONPATH": str(ROOT), "DJANGO_SECRET_KEY": "k" * 60},
+ )
+ assert result.returncode == 0, result.stderr
+
+
+# --- ADR-55: the worker is its own process -----------------------------------------------------
+
+
+def test_worker_runs_one_tick_and_exits():
+ """ARC-71: `manage.py run_worker --once` starts, ticks and stops."""
+ call_command("run_worker", "--once")
+
+
+@pytest.mark.django_db
+def test_migrations_are_in_sync_with_the_models():
+ """A model change without its migration fails here, not in production."""
+ call_command("makemigrations", "--check", "--dry-run")
diff --git a/tests/unit/test_container_hardening.py b/tests/unit/test_container_hardening.py
index 060bcfe..7033fa9 100644
--- a/tests/unit/test_container_hardening.py
+++ b/tests/unit/test_container_hardening.py
@@ -32,8 +32,8 @@ def test_every_locked_requirement_carries_a_hash():
def test_compose_pins_caddy_and_keeps_the_key_out_of_the_environment():
compose = _read("docker-compose.yml")
assert re.search(r"image: caddy:2-alpine@sha256:[0-9a-f]{64}", compose)
- assert "XPRV_ENCRYPTION_KEY_FILE=/run/secrets/xprv_encryption_key" in compose
- assert "file: ./secrets/xprv_encryption.key" in compose
+ # The Django stack carries no master key until the worker needs it (roadmap B4); when it
+ # returns it must again be a compose secret mounted as a file, never an environment value.
assert not re.search(r"XPRV_ENCRYPTION_KEY=", compose)
assert "data-permissions" in compose and "service_completed_successfully" in compose
diff --git a/tests/unit/test_observability.py b/tests/unit/test_observability.py
index f750643..5b9ba6c 100644
--- a/tests/unit/test_observability.py
+++ b/tests/unit/test_observability.py
@@ -190,6 +190,7 @@ def test_uvicorn_trusts_only_the_proxy_and_the_container_is_checked():
root = Path(__file__).resolve().parents[2]
dockerfile, compose = (root / "Dockerfile").read_text(), (root / "docker-compose.yml").read_text()
- assert "--proxy-headers" in dockerfile and "--forwarded-allow-ips" in dockerfile
+ # Django stack (ADR-54): gunicorn trusts the forwarded headers of Caddy's fixed address only.
+ assert "gunicorn" in dockerfile and "--forwarded-allow-ips" in dockerfile
assert "FORWARDED_ALLOW_IPS=172.28.0.10" in compose and "ipv4_address: 172.28.0.10" in compose
- assert "subnet: 172.28.0.0/24" in compose and "/health/ready" in compose
+ assert "subnet: 172.28.0.0/24" in compose and "/health/live" in compose