# 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"]