loopable / Dockerfile
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
85f794d verified
Raw History Blame Contribute Delete
9.75 kB
# AIOS web β€” the React shell + FastAPI over the platform data layer. THE CANONICAL IMAGE:
# this is the one that actually runs, and the one a host migration re-points (C1e).
#
# β›” WHY A SECOND DOCKERFILE EXISTS (ops/Dockerfile.api), stated here so nobody "tidies" the wrong
# one away. It is NOT a duplicated service β€” it is the SAME service built from a DIFFERENT BUILD
# CONTEXT:
# * HF Spaces: the context is the Space repo root, which `deploy_web.py` uploads FLATTENED β€”
# `api/`, `web/`, `platform/`, `requirements.txt` all at top level. Hence the paths here.
# * ops/compose.yml: the context is the local repo root, where the same files live at
# `aios-web/api/`, `aios-web/web/`, `platform/`. Different prefixes, same content.
# β‡’ THE REAL FIX, and it is a follow-up rather than something to do the day of a first deploy:
# make `deploy_web.py` upload with the REPO layout so both contexts are identical, then this file
# serves both and `ops/Dockerfile.api` is deleted. Until then `ops/verify_portability.py` gates
# the two against each other on every property that matters (same app object, same launcher
# contract, non-root, healthchecked, no baked secrets), so they cannot drift silently.
#
# Two stages: node builds the React bundle, python serves it + the JSON API. Login is the app's own
# branded page over a signed session cookie (wave 1 removed the HTTP Basic gate).
# Kamal uses this same flattened build context, including jobs/, instead of the repository root.
# ---- stage 1: build the React bundle ----
FROM node:22-slim AS web
WORKDIR /web
# The lockfile is the audited supply-chain boundary. It now resolves entirely from the public
# registry; discarding it here made every image an unreviewed dependency upgrade.
#
# β›”β›” THE LOCKFILE IS GENERATED ON LINUX, NEVER ON WINDOWS (W-170, 2026-09-13). A Windows-resolved
# lockfile fails `npm ci` in this stage (`Missing: @emnapi/runtime@1.11.3 from lock file`): npm
# records the platform closure of the box that ran it, and `npm ci` treats an absent entry as a
# fatal mismatch. A lockfile resolved natively on Linux (no `--os`/`--cpu`) passes `npm ci` on
# BOTH Linux and Windows -- measured the same day, 198 packages in 52s on the laptop. Regenerate
# ONLY with `python .claude/skills/deploy/scripts/lockfile_linux.py` (one small HF job that runs
# `npm ci` there first and writes `web/package-lock.linux.sha256`); `verify_lockfile.py` reddens
# the battery when the lockfile on disk is not the one that receipt attests.
# W59-T35 reached the same Linux resolve independently in the wave-59 container (Node 22.23.2 /
# npm 10.9.8) and added `--engine-strict`, which makes the `engines` pin in package.json a build
# failure on a mismatched toolchain rather than a warning.
COPY web/package.json web/package-lock.json ./
RUN npm ci --no-audit --no-fund --ignore-scripts --engine-strict
# Keep the resolved build tree: the final image has the bundle but no Node installation.
RUN mkdir -p /deps && npm ls --all --json > /deps/web-deps.json
COPY web/ ./
RUN npm run build # -> /web/dist
# ---- stage 2: python API serving the bundle ----
FROM python:3.12-slim-trixie
WORKDIR /app
# Chromium's libraries match the reviewed Playwright Debian 13 dependency list.
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
fonts-liberation libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 \
libatspi2.0-0t64 libcairo2 libcups2t64 libdbus-1-3 libdrm2 libgbm1 \
libglib2.0-0t64 libnspr4 libnss3 libpango-1.0-0 libx11-6 libxcb1 \
libxcomposite1 libxdamage1 libxext6 libxfixes3 libxkbcommon0 libxrandr2 \
&& rm -rf /var/lib/apt/lists/*
COPY requirements.txt ./
# W59-T35, 2026-09-13: pin the locally installed resolver instead of upgrading pip implicitly.
# The Space uploader still sends aios-web/requirements.txt with open bounds and excludes the
# pinned api/requirements.txt. Wiring those pins into the upload is a separate deployment fix;
# changing COPY to api/requirements.txt alone would refer to a file absent from the Space.
RUN python -m pip install --no-cache-dir --disable-pip-version-check --upgrade "pip==25.0.1" \
&& python -m pip install --no-cache-dir --disable-pip-version-check -r requirements.txt
COPY api/ ./api/
COPY VERSION ./VERSION
# the reused data layer (modules/core/harness)
# β›” COMMENT ON ITS OWN LINE. Docker does NOT support a trailing comment on an instruction:
# it parsed `# the reused data layer ...` as extra SOURCE PATHS and the first build ever run
# died with `failed to calculate checksum ... "/the": not found`. Only RUN tolerates it, and
# only because the shell eats the `#`. Gated in ops/verify_portability.py.
COPY platform/ ./platform/
# the ephemeral-HF-Job scripts the API submits BY PATH (wave 31, R10/C5)
# β›” WITHOUT THIS LINE THE DEPLOY UPLOADS jobs/ AND THE IMAGE STILL DOES NOT HAVE IT. Found at
# wave 31 close: `deploy_web.py::_jobs_files()` was fixed to SHIP the two files, `--check` proved
# `jobs=2`, and the container would still have answered "the browser job's script is missing from
# this deployment" β€” because reaching the Space REPO and reaching the IMAGE are two different
# things, and only this instruction does the second. Same shape as the manifest defect one layer
# up: a file the product opens BY PATH is invisible to every import-following guard we own.
COPY jobs/ ./jobs/
COPY --from=web /web/dist ./web/dist
COPY --from=web /deps/web-deps.json ./deps/web-deps.json
# Run unprivileged β€” the C2 security baseline, and matched to ops/Dockerfile.api so the two images
# do not differ on a property that would only surface after a migration. uid 1000 is what HF
# Spaces expects.
RUN useradd --create-home --uid 1000 user && chown -R user:user /app
USER user
ENV RI_DIR=/app/platform \
PORT=7860 \
FORWARDED_ALLOW_IPS=* \
PYTHONUNBUFFERED=1 \
AIOS_PREWARM=1
# β›” AIOS_INSECURE_SSL is deliberately NOT set. It disables TLS verification for every outbound
# call in the process and exists for one developer laptop. ops/verify_portability.py fails if any
# deploy config sets it.
EXPOSE 7860
# Liveness via stdlib rather than curl β€” it keeps the image free of an apt layer that exists only
# for the healthcheck.
HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
CMD python -c "import os,urllib.request,sys; sys.exit(0 if urllib.request.urlopen(f'http://127.0.0.1:{os.environ.get(\"PORT\",\"7860\")}/api/health',timeout=4).status==200 else 1)"
# ⚠ THE PORT COMES FROM THE ENVIRONMENT, ALWAYS. The application itself reads PORT nowhere β€” it is
# a launcher argument β€” which is what makes moving hosts a config change instead of a code change.
# Secrets (Odoo creds, APP_PASSWORD, AIOS_SESSION_SECRET, APP_BASE_URL) arrive as env at RUN time
# and are never baked; the repo-root .dockerignore drops **/.env from the build context.
# W59-T35: the Space terminates TLS at its ingress proxy, so honour its forwarded scheme/client.
# '*' assumes the container is unreachable except through that trusted proxy, which must replace
# client-supplied forwarded headers. For any direct ingress, set FORWARDED_ALLOW_IPS to the actual
# proxy IPs/CIDRs before exposing the port; do not carry wildcard trust onto a public listener.
# Suppress the server banner. W59-T36 owns the API posture read-back and application host/header
# policy; these flags are its launcher seam.
#
# SDLC 67 close (2026-09-29): `--timeout-keep-alive 5` was the suspected cause of a measured
# 4-12% 502 rate at the HF proxy -- uvicorn closes an idle keep-alive socket after 5s, and if the
# proxy in front of it still believes that connection is reusable and forwards a request onto it,
# the client sees a 502 rather than a fresh connection (the classic reverse-proxy keep-alive race:
# https://adamcrowder.net/posts/node-express-api-and-aws-alb-502/ describes the same shape against
# an ALB). The fix is always the same direction -- make the BACKEND's idle timeout longer than
# whatever the front proxy holds a connection for, never shorter -- because only the side with the
# longer timeout can be the one to close first. HF's Spaces proxy timeout is not published; 75s is
# nginx's own keepalive_timeout default and comfortably exceeds the AWS ALB default (60s) other
# proxies in this class use, so it is the safest available floor without over-fitting to a number
# we cannot read. Re-aim this value again, never delete the flag, if a measurement finds otherwise.
#
# S79-T37 (R25): the launcher sizes the web tier to the container. `request_class.py --env` reads
# the cgroup CPU and memory limits (never os.cpu_count(), which reports the host) and exports the
# uvicorn worker count, heavy concurrency and DuckDB caps. An env value set on the Space wins.
# Several workers require an explicit AIOS_MIRROR_VERSIONS=1 input and the web role.
# Without that opt-in, --env exports one worker and the shell keeps W at 1.
# Measure unloaded staging freshness and peak RSS before raising its worker count.
# On 2 vCPU, two workers also require AIOS_UVICORN_WORKERS=2.
# Several workers load the app through a factory: uvicorn imports a plain app string in its
# supervisor too, and that process would run the boot threads without serving.
CMD ["sh", "-c", "eval \"$(python api/request_class.py --env)\"; W=1; if [ \"${AIOS_MIRROR_VERSIONS:-0}\" = 1 ]; then W=\"${AIOS_UVICORN_WORKERS:-1}\"; fi; export AIOS_UVICORN_WORKERS=\"$W\"; APP=api.main:app; if [ \"$W\" -gt 1 ]; then APP=\"--factory api.request_class:web_app\"; fi; exec uvicorn $APP --host 0.0.0.0 --port ${PORT} --workers \"$W\" --proxy-headers --forwarded-allow-ips \"${FORWARDED_ALLOW_IPS}\" --no-server-header --timeout-keep-alive 75"]