switch docker image

docs/superpowers/plans/2026-06-14-debian-slim-image.md

@@ -0,0 +1,226 @@
+# Debian Slim Backend Image Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the Alpine backend image with Debian slim while improving dependency installation speed and preserving runtime behavior.
+
+**Architecture:** Keep the existing single-stage backend image and process model. Use Debian runtime packages plus manylinux Python wheels, then adapt the shell entrypoint and nginx worker account to Debian conventions.
+
+**Tech Stack:** Docker BuildKit, Python 3.12 slim-bookworm, Debian apt, POSIX shell, nginx, supervisord
+
+---
+
+### Task 1: Establish Migration Checks
+
+**Files:**
+- Inspect: `Dockerfile`
+- Inspect: `deploy/entrypoint.sh`
+- Inspect: `deploy/nginx/nginx.conf`
+
+- [x] **Step 1: Verify the current base image check fails**
+
+Run:
+
+```bash
+grep -q '^FROM python:3\.12-slim-bookworm$' Dockerfile
+```
+
+Expected: exit status 1 because the current image is Alpine.
+
+- [x] **Step 2: Verify the current shell portability check fails**
+
+Run:
+
+```bash
+sh -n deploy/entrypoint.sh
+! grep -n '\[\[' deploy/entrypoint.sh
+```
+
+Expected: `sh -n` succeeds, but the grep assertion exits non-zero because the script contains `[[`.
+
+- [x] **Step 3: Verify the current nginx user check fails**
+
+Run:
+
+```bash
+grep -q '^user www-data;$' deploy/nginx/nginx.conf
+```
+
+Expected: exit status 1 because the configuration uses the Alpine `nginx` account.
+
+### Task 2: Migrate the Docker Build
+
+**Files:**
+- Modify: `Dockerfile`
+
+- [x] **Step 1: Replace the Alpine build with Debian slim**
+
+Use this package and cache structure:
+
+```dockerfile
+FROM python:3.12-slim-bookworm
+ARG TARGETARCH
+ARG TARGETVARIANT
+
+ENV OJ_ENV=production
+WORKDIR /app
+
+COPY ./deploy/requirements.txt /app/deploy/
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked,id=apt-cache-$TARGETARCH$TARGETVARIANT-final \
+    --mount=type=cache,target=/root/.cache/pip,id=pip-cache-$TARGETARCH$TARGETVARIANT-final \
+    <<EOS
+set -ex
+pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
+apt-get update
+apt-get install -y --no-install-recommends \
+  ca-certificates \
+  clang-format \
+  curl \
+  libjpeg62-turbo \
+  libpq5 \
+  nginx \
+  openssl \
+  passwd \
+  supervisor \
+  unzip \
+  zlib1g
+pip install -r /app/deploy/requirements.txt
+rm -rf /var/lib/apt/lists/*
+EOS
+```
+
+Keep the existing application copy, permissions, health check, exposed port, and entrypoint.
+
+- [x] **Step 2: Run Dockerfile static checks**
+
+Run:
+
+```bash
+grep -q '^FROM python:3\.12-slim-bookworm$' Dockerfile
+! grep -nE 'apk|alpine|gcc|python3-dev|--no-cache-dir' Dockerfile
+grep -q 'target=/var/cache/apt' Dockerfile
+grep -q 'target=/root/.cache/pip' Dockerfile
+```
+
+Expected: all checks exit 0.
+
+### Task 3: Make Runtime Configuration Debian-Compatible
+
+**Files:**
+- Modify: `deploy/entrypoint.sh`
+- Modify: `deploy/nginx/nginx.conf`
+
+- [x] **Step 1: Replace non-POSIX tests and Alpine account commands**
+
+Use POSIX `[ ]` tests. Replace runtime account creation with:
+
+```sh
+if ! getent group spj >/dev/null; then
+    groupadd --system --gid 903 spj
+fi
+if ! id -u server >/dev/null 2>&1; then
+    useradd --system --uid 900 --gid spj --no-create-home --shell /usr/sbin/nologin server
+fi
+```
+
+Quote filesystem paths and variable expansions touched by the script.
+
+- [x] **Step 2: Change the nginx worker user**
+
+Set the first line of `deploy/nginx/nginx.conf` to:
+
+```nginx
+user www-data;
+```
+
+- [x] **Step 3: Run runtime configuration checks**
+
+Run:
+
+```bash
+sh -n deploy/entrypoint.sh
+! grep -n '\[\[' deploy/entrypoint.sh
+! grep -nE 'addgroup|adduser' deploy/entrypoint.sh
+grep -q 'groupadd --system --gid 903 spj' deploy/entrypoint.sh
+grep -q 'useradd --system --uid 900 --gid spj' deploy/entrypoint.sh
+grep -q '^user www-data;$' deploy/nginx/nginx.conf
+```
+
+Expected: all checks exit 0.
+
+### Task 4: Build And Inspect The Image
+
+**Files:**
+- Verify: `Dockerfile`
+- Verify: `deploy/entrypoint.sh`
+- Verify: `deploy/nginx/nginx.conf`
+
+- [ ] **Step 1: Build the backend image**
+
+Run:
+
+```bash
+DOCKER_BUILDKIT=1 docker build --progress=plain -t onlinejudge-backend:slim .
+```
+
+Expected: exit status 0, with Python dependencies installed from wheels.
+
+- [ ] **Step 2: Verify native dependencies and runtime tools**
+
+Run:
+
+```bash
+docker run --rm --entrypoint /bin/sh onlinejudge-backend:slim -c \
+  'python -c "from PIL import Image; import lxml.etree; import psycopg" &&
+   clang-format --version &&
+   nginx -t -c /app/deploy/nginx/nginx.conf &&
+   supervisord --version &&
+   openssl version &&
+   groupadd --help >/dev/null &&
+   useradd --help >/dev/null'
+```
+
+Expected: exit status 0.
+
+- [ ] **Step 3: Exercise distribution-specific entrypoint startup**
+
+Run the image with unreachable local service names and a timeout:
+
+```bash
+timeout 15 docker run --rm \
+  -e POSTGRES_HOST=127.0.0.1 \
+  -e REDIS_HOST=127.0.0.1 \
+  -e JUDGE_SERVER_TOKEN=test \
+  onlinejudge-backend:slim
+```
+
+Expected: the application may time out while retrying database migration, but output must not contain shell syntax errors, missing `groupadd`/`useradd`, missing shared libraries, or an unknown nginx user.
+
+### Task 5: Final Verification
+
+**Files:**
+- Verify: all modified files
+
+- [ ] **Step 1: Run repository checks**
+
+Run:
+
+```bash
+git diff --check
+sh -n deploy/entrypoint.sh
+git status --short
+git diff -- Dockerfile deploy/entrypoint.sh deploy/nginx/nginx.conf
+```
+
+Expected: no whitespace errors or shell syntax errors; the diff contains only the approved migration and its documentation.
+
+- [ ] **Step 2: Record build evidence**
+
+Record the image ID and size:
+
+```bash
+docker image inspect onlinejudge-backend:slim --format '{{.Id}} {{.Size}}'
+```
+
+Expected: one image ID and byte size.

docs/superpowers/specs/2026-06-14-debian-slim-image-design.md

@@ -25,6 +25,7 @@ Replace Alpine `apk` commands with Debian `apt-get` commands. Install only runti
 - `libpq5`
 - `nginx`
 - `openssl`
+- `passwd`
 - `supervisor`
 - `unzip`
 - `zlib1g`