diff --git a/.agents/skills/n2api-local-refresh/SKILL.md b/.agents/skills/n2api-local-refresh/SKILL.md index 5b7d795c..890dea40 100644 --- a/.agents/skills/n2api-local-refresh/SKILL.md +++ b/.agents/skills/n2api-local-refresh/SKILL.md @@ -1,68 +1,59 @@ --- name: n2api-local-refresh -description: Rebuild, recreate, and verify the local N2API Docker Compose development stack after repository code or functionality changes. Use when Codex finishes an N2API implementation, needs the running local stack to reflect source changes, or the user asks to refresh, rebuild, or recreate the local N2API deployment. +description: Rebuild, recreate, verify, and tear down the local N2API Docker Compose development stack after code changes, preserving persistent data. Use for local development refresh and session cleanup. --- # N2API Local Refresh -Run this workflow from the repository root after relevant code or functionality changes. +Run this workflow from the task worktree after code or functionality changes. +Apply the repository's current session rules instead of leaving a detached +development stack running. No production operation is authorized here. ## Refresh -1. Confirm the intended repository changes and relevant tests are complete. -2. Remove unused builder cache from earlier builds: +1. Confirm the intended changes and relevant tests are complete. Check that no + other build is using the shared builder before builder-wide cache cleanup. +2. Configure temporary files and controlled caches on the required mounted + remote filesystem through `TMPDIR`, `TMP`, `TEMP`, `N2API_TMP_ROOT`, and + `N2API_DEV_CACHE_ROOT`. Verify the mount and available space before writing. +3. Run the managed one-shot refresh: ```bash - docker builder prune --all --force + make dev-check ``` -3. Rebuild without cache: - - ```bash - docker compose -f deploy/compose.yaml build --no-cache - ``` - -4. Recreate the development stack without deleting data: - - ```bash - docker compose -f deploy/compose.yaml up -d --force-recreate - ``` +The runner prunes unused builder cache, builds with `--no-cache`, recreates and +waits for the development services to become healthy, and probes `/livez`, +`/readyz`, `/version`, and `/` inside the app container. On exit it removes the +development containers, network, locally built app image, and run directory, +then prunes unused builder cache. Named PostgreSQL data and backups remain. ## Verify -1. Require `n2api` and `postgres` to be running and healthy: +After the command, require no remaining development containers or network and +confirm the existing volume still exists: - ```bash - docker compose -f deploy/compose.yaml ps - ``` +```bash +docker ps -a --filter label=com.docker.compose.project=deploy +docker network ls --filter label=com.docker.compose.project=deploy +docker volume inspect deploy_n2api-postgres --format '{{.Name}}' +``` -2. Resolve the current application container and run probes inside it: +Report the exact commands, probe results, teardown, and preserved data. A failed +probe or incomplete cleanup is a failure; inspect the error and retain useful +diagnostic evidence before resolving it. Do not leave failed containers running +by default. - ```bash - container_id="$(docker compose -f deploy/compose.yaml ps --quiet n2api)" - docker exec "${container_id}" wget -qO- http://127.0.0.1:3000/livez - docker exec "${container_id}" wget -qO- http://127.0.0.1:3000/readyz - docker exec "${container_id}" wget -qO- http://127.0.0.1:3000/version - ``` - -3. Run a container-local bootstrap page smoke check: - - ```bash - docker exec "${container_id}" wget -qO- http://127.0.0.1:3000/ - ``` - -4. Remove build cache created by the no-cache rebuild only after recreation and verification succeed: - - ```bash - docker builder prune --all --force - ``` +## Interactive Development -Report the exact commands, Compose service state, and probe results. +Use `make dev` to keep a foreground session open. Ctrl-C, TERM, or HUP tears it +down. Keep a preview running beyond verification only when the user explicitly +requests it, and report how to stop it. Use `make dev-stop` after a hard kill, +host failure, or a legacy detached startup; never stop another active session. ## Boundaries -- Do not run `docker system prune`. -- Do not prune images or volumes. -- Do not run `compose down`, delete the PostgreSQL volume, or reset application data. -- Do not substitute the production Compose file for this local refresh. -- If verification fails, preserve the stack and inspect logs; do not report success or perform destructive cleanup. +- Do not use global system/image/volume prune or development `down --volumes`. +- Do not remove PostgreSQL data, credentials, backups, or unrelated resources. +- Do not substitute production Compose or change the host Docker daemon. +- Disposable labelled test volumes remain managed by their isolated test runner. diff --git a/AGENTS.md b/AGENTS.md index 811a862a..c20a70c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,6 +73,33 @@ - Prefer Docker Compose for local full-stack verification. - Do not introduce Node.js, npm, npx, pnpm, or yarn unless Bun cannot support a required package or workflow. +## Local Development Sessions +- Local full-stack development and testing use Docker Compose only when + explicitly needed by the current project session. Use `make dev` for a + foreground development session, `make dev-check` for rebuild/probe/teardown, + and `make dev-stop` for an abandoned detached development stack. +- Development containers must use `restart: "no"`. Do not install boot tasks, + timers, restart policies, or other automation that starts the development + stack outside an explicit session. The Docker daemon is shared host + infrastructure; do not stop, disable, or reconfigure it for project cleanup. +- After development verification, close the session and verify that development + containers and networks are gone. Do not leave a detached stack running at + the end of a turn unless the user explicitly requests a continuing preview. +- Remove current-run temporary files, build output, disposable test containers, + test networks, labelled test volumes/images, and unused builder cache. Use + the managed test lifecycle and `make clean-dev-artifacts` for inactive + labelled residue; never use broad system/image/volume prune commands. +- Preserve `deploy_n2api-postgres`, existing application configuration, + credentials, backups, useful failure/acceptance evidence, unrelated resources, + and other active sessions. Deleting persistent development data needs an + explicit reset request. Never run development `compose down --volumes`. +- Keep temporary outputs and controlled caches on the configured mounted remote + filesystem through `TMPDIR`, `TMP`, `TEMP`, `N2API_TMP_ROOT`, and + `N2API_DEV_CACHE_ROOT`. The zero-byte ownership lock in the primary checkout's + `.cache/` is the local exception so all worktrees share a kernel lock. +- See `docs/development.md` for session lifetime, signal/crash recovery, and + cleanup boundaries. + ## Operations Skills - Use `.agents/skills/n2api-local-refresh/SKILL.md` for the required non-destructive local Compose rebuild, recreation, verification, and builder @@ -101,8 +128,14 @@ - Use Conventional Commits for commit messages, such as `feat: add provider health check`, `fix: preserve streaming response headers`, `docs: update deployment guide`, `test: cover token refresh`, or `chore: update tooling`. - Follow the standing authorization and review gates in **Worktree And Pull Request Workflow** for task branches and PRs. Other remote writes, tags, releases, and repository-setting changes require an explicit user request. - Do not commit generated build artifacts, dependency directories, local caches, or real environment files. -- After every conversation turn that involves code or functionality changes, rebuild and refresh the local Docker Compose dev stack so the user can test and verify. Use the `n2api-refresh-docker` skill for the exact commands. If no code or functionality was changed during the turn, skip this step. -- Because the local Compose refresh uses `--no-cache`, run `docker builder prune --all --force` immediately before the rebuild to remove unused cache from previous builds and again after a successful rebuild, recreation, and verification so the new build cache does not accumulate. This cleanup is builder-wide. Do not automatically run `docker system prune`, prune images, or prune volumes. +- After every conversation turn that involves code or functionality changes, + run `make dev-check` using `.agents/skills/n2api-local-refresh/SKILL.md`. + This performs a no-cache rebuild, recreation, health/page probes, and teardown + while preserving PostgreSQL data. Documentation-only changes skip this step. +- The session runner prunes unused builder cache before building and during + teardown. This cleanup is builder-wide; do not run it concurrently with other + builds. Only the development project's locally built image is removed by + its Compose teardown; never globally prune images or volumes. - Do not inspect or poll GitHub CI for local commits that have not been pushed. Only after a user-authorized push succeeds, or after a merge has otherwise reached GitHub, wait for the corresponding `CI Image` workflow run to complete before claiming the remote workflow is finished. Ordinary PR and `main` runs must pass `Test` and their applicable correctness checks; delivery build, image smoke, publication, and evidence jobs are expected to be skipped. Only Release `publish` enables the full build chain, and its platform image tests, pushes, and evidence must pass before stable promotion. Release `preview` must not build or publish images. Do not dispatch a publish run without an explicit release request. If a workflow fails, inspect its logs and resolve the failure before closing the task. ## Subagent Workflow diff --git a/Makefile b/Makefile index b76e1f4e..e86fb466 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,19 @@ SHELL := /usr/bin/env bash +.DEFAULT_GOAL := test -.PHONY: test test-ops ops-describe ops-doctor test-go-quality test-critical-race test-control-connections test-postgres-faults test-request-log-profile test-management-list-profile test-production-deploy test-e2e test-contracts test-playwright playwright-install \ +.PHONY: dev dev-check dev-stop test test-ops ops-describe ops-doctor test-go-quality test-critical-race test-control-connections test-postgres-faults test-request-log-profile test-management-list-profile test-production-deploy test-e2e test-contracts test-playwright playwright-install \ disk-check disk-check-heavy clean-dev-artifacts clean-dev-artifacts-deep \ test-dev-artifacts test-restore-backup backup-dev +dev: + dev/development/run.sh session + +dev-check: + dev/development/run.sh check + +dev-stop: + dev/development/run.sh stop + test: dev/testing/run.sh unit @@ -64,6 +74,7 @@ clean-dev-artifacts-deep: test-dev-artifacts: dev/ci/test-dev-artifacts.sh + dev/ci/test-dev-session.sh dev/ci/test-postgres-backup.sh test-restore-backup: diff --git a/README.md b/README.md index 8686c3e6..ceaec29c 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ operations. ## Quick Start -Requirements: Docker Engine with Docker Compose v2. +Requirements: Docker Engine with Docker Compose v2, Git, Make, and Bash. ```bash git clone https://github.com/KnowSky404/N2API.git @@ -39,11 +39,17 @@ Replace every `change-me` value in `.env`. At minimum, configure a strong start the stack: ```bash -docker compose -f deploy/compose.yaml --env-file .env up --build +make dev ``` Open `http://localhost:3000` and sign in with the admin credentials from -`.env`. The development Compose file explicitly accepts its HTTP public origin, +`.env`. Keep the command open during development; Ctrl-C removes the containers +and network while preserving the database and backups. Services do not restart +automatically. Use `make dev-check` for one-shot verification and +`make dev-stop` for abandoned detached containers. See the +[development lifecycle](docs/development.md) for cleanup and remote access. + +The development Compose file explicitly accepts its HTTP public origin, container wildcard bind, and plaintext private-network database topology; published-image deployments remain fail-closed until those risks are selected individually. See the [operator manual](docs/manual.md#host-binding-modes) for diff --git a/deploy/compose.yaml b/deploy/compose.yaml index 96ec0568..ca03fa3e 100644 --- a/deploy/compose.yaml +++ b/deploy/compose.yaml @@ -3,7 +3,7 @@ services: build: context: .. dockerfile: deploy/Dockerfile - restart: unless-stopped + restart: "no" read_only: true tmpfs: - /tmp:rw,noexec,nosuid,nodev,size=16m,mode=1777,uid=10001,gid=10001 @@ -14,7 +14,7 @@ services: stop_grace_period: 35s env_file: - path: ../.env.example - - path: ../.env + - path: ${N2API_ENV_FILE:-../.env} required: false environment: N2API_ACCEPT_RISKS: ${N2API_ACCEPT_RISKS:-public-http,public-bind,database-plaintext} @@ -37,6 +37,7 @@ services: postgres: image: postgres:18.6-alpine3.23@sha256:885cf05d376c7cf27afef02073e6bdac3841252537f16e244fd1c1e6a7c99fb1 + restart: "no" environment: POSTGRES_DB: ${POSTGRES_DB:-n2api} POSTGRES_USER: ${POSTGRES_USER:-n2api} @@ -51,7 +52,7 @@ services: postgres-backup: image: postgres:18.6-alpine3.23@sha256:885cf05d376c7cf27afef02073e6bdac3841252537f16e244fd1c1e6a7c99fb1 - restart: unless-stopped + restart: "no" entrypoint: ["/usr/local/bin/n2api-postgres-backup"] command: ["daemon"] environment: @@ -65,13 +66,14 @@ services: N2API_BACKUP_GID: ${N2API_BACKUP_GID:-1000} volumes: - ./postgres-backup.sh:/usr/local/bin/n2api-postgres-backup:ro - - ../backups:/backups + - ${N2API_DEV_BACKUP_DIR:-../backups}:/backups depends_on: postgres: condition: service_healthy read_only: true tmpfs: - /tmp:rw,noexec,nosuid,nodev,size=4m,mode=1777 + - /var/lib/postgresql:rw,noexec,nosuid,nodev,size=1m,mode=1777 security_opt: - no-new-privileges:true cap_drop: diff --git a/dev/ci/test-dev-session.sh b/dev/ci/test-dev-session.sh new file mode 100755 index 00000000..646a1839 --- /dev/null +++ b/dev/ci/test-dev-session.sh @@ -0,0 +1,170 @@ +#!/usr/bin/env bash + +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)" +runner="${repo_root}/dev/development/run.sh" +fixture="$(mktemp -d "${TMPDIR:-/tmp}/n2api-dev-session-test.XXXXXXXX")" +cleanup() { + local status=$? compose_pid + if [[ -n "${session_pid:-}" ]]; then + kill -KILL "${session_pid}" 2>/dev/null || true + wait "${session_pid}" 2>/dev/null || true + fi + if [[ -f "${fixture}/compose.pid" ]]; then + read -r compose_pid <"${fixture}/compose.pid" + kill -KILL -- "-${compose_pid}" 2>/dev/null || true + fi + if (( status != 0 )); then + cat "${fixture}/run.log" >&2 || true + fi + rm -rf -- "${fixture}" +} +trap cleanup EXIT +mkdir -p "${fixture}/bin" "${fixture}/primary" "${fixture}/tmp" + +fail() { echo "FAIL: $*" >&2; exit 1; } + +cat >"${fixture}/bin/git" <<'GIT' +#!/usr/bin/env bash +printf 'worktree %s\n' "${N2API_SESSION_FIXTURE}/primary" +printf 'worktree %s\n' "${N2API_SESSION_FIXTURE}/other-task" +GIT +cat >"${fixture}/bin/docker" <<'DOCKER' +#!/usr/bin/env bash +set -euo pipefail +printf '%s\n' "$*" >>"${N2API_SESSION_FIXTURE}/docker.log" +case "$*" in + compose*" ps --all --quiet") echo existing-dev ;; + inspect*) + if [[ "${N2API_FAKE_FOREIGN:-0}" == 1 ]]; then + echo "${N2API_SESSION_FIXTURE}/primary/deploy/compose.release.yaml" + elif [[ "${N2API_FAKE_PREVIOUS_WORKTREE:-0}" == 1 ]]; then + echo "${N2API_SESSION_FIXTURE}/other-task/deploy/compose.yaml" + elif [[ -n "${N2API_FAKE_CONFIG_FILES:-}" ]]; then + echo "${N2API_FAKE_CONFIG_FILES}" + else + echo "${N2API_SESSION_FIXTURE}/primary/deploy/compose.yaml" + fi + ;; + compose*" ps --quiet n2api") echo dev-app ;; + compose*" build --no-cache") exit "${N2API_FAKE_BUILD_STATUS:-0}" ;; + compose*" up -d "*) exit "${N2API_FAKE_START_STATUS:-0}" ;; + compose*" down "*) exit "${N2API_FAKE_CLEANUP_STATUS:-0}" ;; + compose*" up --no-build "*) + if [[ "${N2API_FAKE_WAIT:-0}" == 1 ]]; then + printf '%s\n' "${BASHPID}" >"${N2API_SESSION_FIXTURE}/compose.pid" + touch "${N2API_SESSION_FIXTURE}/ready" + trap 'exit 0' INT TERM HUP + while :; do sleep 0.1; done + fi + ;; +esac +DOCKER +chmod +x "${fixture}/bin/"* + +export PATH="${fixture}/bin:${PATH}" +export N2API_SESSION_FIXTURE="${fixture}" +export N2API_TMP_ROOT="${fixture}/tmp" +export N2API_DEV_CACHE_ROOT="${fixture}/cache" +export N2API_DISK_MIN_FREE_GIB=0 +export N2API_TEST_COMPOSE_PROJECT=parent-test +export N2API_TEST_COMPOSE_FILE=/parent/compose.e2e.yaml + +assert_cleaned() { + grep -Fq 'down --remove-orphans --rmi local' "${fixture}/docker.log" || fail "development stack was not removed" + if grep -Eq 'down .*--volumes|down .* -v|system prune|image prune|volume (rm|prune)' "${fixture}/docker.log"; then + fail "cleanup crossed the persistent-data boundary" + fi + [[ -z "$(find "${fixture}/tmp" -mindepth 1 -print -quit)" ]] || fail "run directory survived cleanup" +} + +for mode in check session stop; do + : >"${fixture}/docker.log" + "${runner}" "${mode}" >"${fixture}/run.log" 2>&1 + assert_cleaned + if [[ "${mode}" != stop ]]; then + [[ "$(grep -c '^builder prune --all --force$' "${fixture}/docker.log")" == 2 ]] || fail "build cache was not cleaned before and after use" + grep -Fq 'http://127.0.0.1:3000/readyz' "${fixture}/docker.log" || fail "readiness was not checked" + grep -Fq 'http://127.0.0.1:3000/' "${fixture}/docker.log" || fail "bootstrap page was not checked" + fi +done + +: >"${fixture}/docker.log" +N2API_FAKE_PREVIOUS_WORKTREE=1 "${runner}" stop >"${fixture}/run.log" 2>&1 +assert_cleaned + +for worktree in primary other-task; do + : >"${fixture}/docker.log" + N2API_FAKE_CONFIG_FILES="${fixture}/${worktree}/deploy/compose.yaml,${fixture}/${worktree}/deploy/compose.metrics.yaml" \ + "${runner}" stop >"${fixture}/run.log" 2>&1 + assert_cleaned +done + +: >"${fixture}/docker.log" +N2API_DEV_METRICS=1 "${runner}" check >"${fixture}/run.log" 2>&1 +assert_cleaned +grep -Fq -- "--file ${repo_root}/deploy/compose.metrics.yaml" "${fixture}/docker.log" || fail "metrics session did not select its override" + +for failure in N2API_FAKE_START_STATUS=7 N2API_FAKE_CLEANUP_STATUS=1; do + : >"${fixture}/docker.log" + if env "${failure}" "${runner}" check >"${fixture}/run.log" 2>&1; then + fail "${failure} was reported as success" + fi + assert_cleaned +done + +for failure in N2API_FAKE_FOREIGN=1 N2API_FAKE_BUILD_STATUS=7 \ + "N2API_FAKE_CONFIG_FILES=${fixture}/primary/deploy/compose.yaml,${fixture}/primary/deploy/compose.release.yaml" \ + "N2API_FAKE_CONFIG_FILES=${fixture}/primary/deploy/compose.yaml,${fixture}/primary/deploy/unknown.yaml"; do + : >"${fixture}/docker.log" + if env "${failure}" "${runner}" check >"${fixture}/run.log" 2>&1; then + fail "${failure} was reported as success" + fi + if grep -Eq 'compose.* (up|down) ' "${fixture}/docker.log"; then + fail "${failure} changed the pre-existing stack" + fi +done + +for signal in INT TERM HUP; do + : >"${fixture}/docker.log" + rm -f "${fixture}/ready" + env --default-signal=INT N2API_FAKE_WAIT=1 "${runner}" session >"${fixture}/run.log" 2>&1 & + session_pid=$! + for _ in {1..200}; do + [[ -f "${fixture}/ready" ]] && break + sleep 0.02 + done + [[ -f "${fixture}/ready" ]] || fail "foreground session never started" + if "${runner}" stop >"${fixture}/concurrent.log" 2>&1; then + fail "a concurrent stop acquired the active session" + fi + grep -Fq 'reason=active_development_session' "${fixture}/concurrent.log" || fail "concurrent stop failed for an unexpected reason" + kill -s "${signal}" "${session_pid}" + status=0 + wait "${session_pid}" || status=$? + unset session_pid + rm -f "${fixture}/compose.pid" + case "${signal}" in INT) expected=130 ;; TERM) expected=143 ;; HUP) expected=129 ;; esac + [[ "${status}" == "${expected}" ]] || fail "${signal} returned ${status}, expected ${expected}" + assert_cleaned +done + +: >"${fixture}/docker.log" +rm -f "${fixture}/ready" +N2API_FAKE_WAIT=1 N2API_TMP_ROOT="${fixture}/abandoned-tmp" "${runner}" session >"${fixture}/run.log" 2>&1 & +session_pid=$! +for _ in {1..200}; do + [[ -f "${fixture}/ready" ]] && break + sleep 0.02 +done +[[ -f "${fixture}/ready" ]] || fail "foreground session never started" +read -r compose_pid <"${fixture}/compose.pid" +kill -KILL "${session_pid}" +wait "${session_pid}" 2>/dev/null || true +unset session_pid +kill -0 "${compose_pid}" || fail "Compose child did not survive the forced runner exit" +"${runner}" stop >"${fixture}/run.log" 2>&1 +assert_cleaned + +echo "Development session lifecycle tests passed." diff --git a/dev/development/run.sh b/dev/development/run.sh new file mode 100755 index 00000000..2844e6e1 --- /dev/null +++ b/dev/development/run.sh @@ -0,0 +1,101 @@ +#!/usr/bin/env bash + +set -Eeuo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)" +source "${repo_root}/dev/lib/test-resources.sh" + +mode=${1:-session} +case "${mode}" in + session|check|stop) ;; + *) echo "usage: $0 {session|check|stop}" >&2; exit 2 ;; +esac + +worktrees="$(git -C "${repo_root}" worktree list --porcelain | sed -n 's/^worktree //p')" +primary_root="${worktrees%%$'\n'*}" +[[ -n "${primary_root}" ]] || exit 1 +# Keep one local kernel lock across worktrees, independent of temporary paths. +mkdir -p "${primary_root}/.cache" +exec {session_lock_fd}>"${primary_root}/.cache/.n2api-dev-session.lock" +flock -n -x "${session_lock_fd}" || { + echo "development_status=blocked reason=active_development_session" >&2 + exit 1 +} + +export N2API_ENV_FILE="${primary_root}/.env" +export N2API_DEV_BACKUP_DIR="${primary_root}/backups" +compose=(docker compose --project-name deploy --file "${repo_root}/deploy/compose.yaml") +if [[ "${N2API_DEV_METRICS:-0}" == 1 ]]; then + compose+=(--file "${repo_root}/deploy/compose.metrics.yaml") +fi +if [[ -f "${N2API_ENV_FILE}" ]]; then + compose+=(--env-file "${N2API_ENV_FILE}") +fi +containers="$("${compose[@]}" ps --all --quiet)" +while IFS= read -r container; do + [[ -n "${container}" ]] || continue + config_files="$(docker inspect --format '{{ index .Config.Labels "com.docker.compose.project.config_files" }}' "${container}")" + owned=0 + while IFS= read -r worktree; do + case "${config_files}" in + "${worktree}/deploy/compose.yaml"|"${worktree}/deploy/compose.yaml,${worktree}/deploy/compose.metrics.yaml") owned=1 ;; + esac + done <<<"${worktrees}" + if (( owned == 0 )); then + echo "development_status=blocked reason=foreign_compose_project container=${container}" >&2 + exit 1 + fi +done <<<"${containers}" + +if [[ "${mode}" != stop ]]; then + "${repo_root}/dev/maintenance/disk-check.sh" --heavy +fi +unset N2API_TEST_COMPOSE_PROJECT N2API_TEST_COMPOSE_FILE +n2api_run_init dev-session +stack_started=0 +build_started=0 + +cleanup_development() { + local status=$? + trap - EXIT INT TERM HUP + if (( stack_started == 1 )); then + if ! "${compose[@]}" down --remove-orphans --rmi local; then + echo "development_status=failed reason=teardown_incomplete" >&2 + status=1 + fi + fi + if (( build_started == 1 )); then + docker builder prune --all --force || status=1 + fi + n2api_run_cleanup "${status}" +} +trap cleanup_development EXIT + +run_compose() { + # Keep the lock in the runner so surviving children cannot block recovery. + n2api_run_command "${compose[@]}" "$@" {session_lock_fd}>&- +} + +if [[ "${mode}" == stop ]]; then + stack_started=1 + exit 0 +fi + +docker builder prune --all --force +build_started=1 +run_compose build --no-cache +stack_started=1 +run_compose up -d --force-recreate --wait --wait-timeout 120 +"${compose[@]}" ps +container_id="$("${compose[@]}" ps --quiet n2api)" +[[ -n "${container_id}" ]] +for path in livez readyz version; do + docker exec "${container_id}" wget -T 10 -qO- "http://127.0.0.1:3000/${path}" +done +docker exec "${container_id}" wget -T 10 -q -O /dev/null http://127.0.0.1:3000/ +echo "development_status=verified" + +if [[ "${mode}" == session ]]; then + echo "Development session ready; keep this process open and press Ctrl-C to clean up." + run_compose up --no-build --abort-on-container-exit +fi diff --git a/dev/lib/test-resources.sh b/dev/lib/test-resources.sh index c8ddccbe..bb0c8690 100755 --- a/dev/lib/test-resources.sh +++ b/dev/lib/test-resources.sh @@ -47,7 +47,7 @@ n2api_acquire_run_lock() { } mkdir -p "$(dirname "${N2API_RESOURCE_LOCK_FILE}")" if [[ -z "${N2API_RUN_LOCK_FD:-}" ]]; then - exec {N2API_RUN_LOCK_FD}>"${N2API_RESOURCE_LOCK_FILE}" + exec {N2API_RUN_LOCK_FD}<>"${N2API_RESOURCE_LOCK_FILE}" flock -s "${N2API_RUN_LOCK_FD}" fi } @@ -241,7 +241,7 @@ n2api_assert_owned_run_dir() { n2api_run_cleanup() { local status=$1 local artifact_target cleanup_failed=0 - trap - EXIT INT TERM + trap - EXIT INT TERM HUP if [[ -n "${N2API_TEST_COMPOSE_PROJECT:-}" && -n "${N2API_TEST_COMPOSE_FILE:-}" ]]; then n2api_compose down --volumes --remove-orphans --rmi local --timeout 10 >/dev/null 2>&1 || cleanup_failed=1 @@ -276,7 +276,7 @@ n2api_run_cleanup() { n2api_signal_exit() { local signal=$1 local status=$2 - trap - INT TERM + trap - INT TERM HUP if [[ -n "${N2API_CHILD_PID:-}" ]]; then kill -s "${signal}" -- "-${N2API_CHILD_PID}" 2>/dev/null || kill -s "${signal}" "${N2API_CHILD_PID}" 2>/dev/null || true @@ -334,6 +334,7 @@ n2api_run_init() { trap 'n2api_run_cleanup $?' EXIT trap 'n2api_signal_exit INT 130' INT trap 'n2api_signal_exit TERM 143' TERM + trap 'n2api_signal_exit HUP 129' HUP mkdir -p \ "${N2API_RUN_DIR}/tmp" \ "${N2API_RUN_DIR}/go-build" \ @@ -350,6 +351,7 @@ n2api_run_init() { export N2API_RUN_ID N2API_RUN_DIR export N2API_TEST_RUN_ID="${N2API_RUN_ID}" export TMPDIR="${N2API_RUN_DIR}/tmp" + export TMP="${TMPDIR}" TEMP="${TMPDIR}" export XDG_CACHE_HOME="${N2API_RUN_DIR}/cache" export GOCACHE="${N2API_RUN_DIR}/go-build" export GOMODCACHE="${N2API_DEV_CACHE_ROOT}/go-mod" diff --git a/docs/development.md b/docs/development.md index def8abae..5984229d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -4,34 +4,132 @@ N2API's local verification commands isolate temporary files and disposable Docker resources so repeated development runs cannot silently consume the host disk. Use the root `Makefile` instead of creating ad hoc caches under `/tmp`. +## Development Sessions + +Start the local Compose stack explicitly from the current checkout or task +worktree: + +```bash +make dev +``` + +The command rebuilds without cache, waits for healthy services, probes the app, +and stays in the foreground. Keep it open while developing. Ctrl-C, TERM, HUP +(terminal disconnect), a service exit, or a failed start triggers teardown. +The runner removes development containers, the network, the locally built app +image, its temporary directory, and unused builder cache. All services use +`restart: "no"`, so Docker/host restarts do not start a development stack. +Do not add host boot jobs or scheduled startup for local testing. The Docker +daemon is shared infrastructure and stays available to other projects. + +For verification that exits after the health and bootstrap-page checks: + +```bash +make dev-check +``` + +Do not leave detached services running after development verification unless +the user explicitly requests a continuing preview. On this VPS the app is at +`http://oc-de-fra-1.knowsky.uk:3000` while the foreground session is open; +Compose publishes the configured port on IPv4 and IPv6. Other hosts can use +`http://localhost:3000`. + +For host-side metrics, configure the dedicated bearer token described in the +operator manual and use `N2API_DEV_METRICS=1 make dev` or +`N2API_DEV_METRICS=1 make dev-check`. This adds the existing metrics Compose +override. `N2API_METRICS_ENABLED` alone continues to configure the internal +listener without publishing another host port. + +The runner preserves `deploy_n2api-postgres`, the primary checkout's `.env`, +and its `backups/` directory across task worktrees. Closing a session is not a +database reset. Persistent data requires a separate explicit reset request; +never use `down --volumes` for the development project. Disposable test volumes +remain separate and are removed by the creating test runner. + +A zero-byte ownership lock in the primary checkout's +`.cache/.n2api-dev-session.lock` is shared across worktrees. It stays local for +kernel locking, independent of temporary/cache overrides. A second session or +`make dev-stop` refuses to interrupt an active foreground owner. The runner +keeps the lock out of Compose child processes so a killed owner permits recovery. +It accepts the base development file or its known metrics override combination +and refuses a `deploy` project belonging to release or unrelated Compose +files before changing it. + +SIGKILL, a host crash, or an external detached `compose up -d` cannot run an +exit trap. Close those leftovers explicitly once no session is active: + +```bash +make dev-stop +make clean-dev-artifacts +``` + +After cleanup, require no development containers or network and retain the +database volume: + +```bash +docker ps -a --filter label=com.docker.compose.project=deploy +docker network ls --filter label=com.docker.compose.project=deploy +docker volume inspect deploy_n2api-postgres --format '{{.Name}}' +``` + +On this development VPS, verify the mounted remote filesystem and available +space first, then configure artifacts before invoking managed commands: + +```bash +artifact_base=/mnt/oc-de-fra-2/data/oc-de-fra-1/codex +findmnt -T "$artifact_base" +df -h "$artifact_base" +mkdir -p "$artifact_base/tmp/n2api" "$artifact_base/cache/n2api" +task_tmp=$(mktemp -d "$artifact_base/tmp/n2api/session.XXXXXXXX") +export TMPDIR="$task_tmp" TMP="$task_tmp" TEMP="$task_tmp" +export N2API_TMP_ROOT="$task_tmp" +export N2API_DEV_CACHE_ROOT="$artifact_base/cache/n2api" +make dev-check +rmdir "$task_tmp" +``` + +Keep downloads, build output, reports, screenshots, and traces in those managed +locations. Do not silently fall back if the required remote mount is absent. +Docker's existing storage and installed tools stay at their established paths. +Tests that require exact local ownership and permission bits (operator state +and backup fixtures) cannot use the root-squashed NFS mount. For those small +fixtures only, use a private `mktemp -d /tmp/n2api-*-posix.XXXXXXXX`, remove it +after the test, and keep logs and other artifacts remote. + ## Managed Resources Each test run creates a unique directory with `mktemp -d` under -`${N2API_TMP_ROOT:-${TMPDIR:-/tmp}}`. An `EXIT`/`INT`/`TERM` trap removes only +`${N2API_TMP_ROOT:-${TMPDIR:-/tmp}}`. An `EXIT`/`INT`/`TERM`/`HUP` trap removes only that directory. Concurrent runs have distinct run IDs and active markers and hold a shared lifecycle lock. Maintenance requires the exclusive lock, so one run or maintenance command cannot remove another active run. The lifecycle exports these locations: -- `GOCACHE`, `GOTMPDIR`, `GOPATH`, `TMPDIR`, and `XDG_CACHE_HOME` are unique to +- `GOCACHE`, `GOTMPDIR`, `GOPATH`, `TMPDIR`, `TMP`, `TEMP`, and `XDG_CACHE_HOME` are unique to the current run and are deleted at exit. -- `GOMODCACHE` uses `.cache/dev/go-mod` and is deleted after a run if it exceeds +- `GOMODCACHE` uses `${N2API_DEV_CACHE_ROOT}/go-mod` and is deleted after a run if it exceeds `N2API_GO_MOD_CACHE_MAX_MIB` (default `2048`) and no other managed run is active. -- `BUN_INSTALL_CACHE_DIR` uses `.cache/dev/bun`, capped by +- `BUN_INSTALL_CACHE_DIR` uses `${N2API_DEV_CACHE_ROOT}/bun`, capped by `N2API_BUN_CACHE_MAX_MIB` (default `1024`). -- `PLAYWRIGHT_BROWSERS_PATH` uses `.cache/dev/playwright-browsers`, capped by +- `PLAYWRIGHT_BROWSERS_PATH` uses `${N2API_DEV_CACHE_ROOT}/playwright-browsers`, capped by `N2API_PLAYWRIGHT_CACHE_MAX_MIB` (default `2048`). Playwright output, traces, screenshots, and reports stay inside the current run directory. - SvelteKit's bounded `.svelte-kit` workspace remains under `frontend/` so generated server modules can resolve frontend dependencies. The adapter-static `build` output is redirected into the current run directory. - Deep cleanup removes the repository-local `.svelte-kit` workspace. + Deep cleanup removes the repository-local `.svelte-kit` workspace. After + verification, remove current-task generated outputs once no other task uses + them; preserve installed dependencies and active shared tools. + +`N2API_DEV_CACHE_ROOT` defaults to `.cache/dev` on other hosts; set it to the +verified remote cache path on this VPS. Bounded download caches are reused; +per-run intermediate files and build outputs are removed on every exit. Failed Playwright evidence is deleted by default. Set `N2API_KEEP_FAILED_ARTIFACTS=1` to retain it under -`.cache/dev/artifacts/`. Regular cleanup keeps at most five sets for +`${N2API_DEV_CACHE_ROOT}/artifacts/`. Regular cleanup keeps at most five sets for seven days by default; override `N2API_ARTIFACT_KEEP_COUNT` or `N2API_ARTIFACT_TTL_DAYS` when needed. @@ -83,7 +181,7 @@ Managed cleanup removes every test database volume. ## Local Database Backups -The development Compose stack starts `postgres-backup` after PostgreSQL is +The foreground development session starts `postgres-backup` after PostgreSQL is healthy. It creates a custom-format dump immediately and every six hours by default, validates each archive with `pg_restore --list`, then atomically moves it into the ignored `backups/` directory. The directory is `0750` and archives @@ -91,7 +189,9 @@ are `0640`, owned by root and the configured host operator group. Set `N2API_BACKUP_GID` in `.env` to the numeric result of `id -g` for the operator who copies or restores backups; it defaults to `1000`. Existing matching dumps are normalized when the sidecar starts. Files older than seven days are -removed. Override the bounded interval and retention with +removed by the backup sidecar's retention policy. The sidecar stops with the +development session and does not run independently between sessions. Override +the bounded interval and retention with `N2API_BACKUP_INTERVAL_SECONDS` and `N2API_BACKUP_RETENTION_DAYS` in `.env`. Create and validate an additional backup immediately: diff --git a/docs/manual.md b/docs/manual.md index 088678c5..7aecfb6b 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -9,13 +9,21 @@ deployment target is Docker Compose on a small VPS. From the repository root: ```bash -docker compose -f deploy/compose.yaml up --build +make dev ``` The default app URL is `http://localhost:3000`. This zero-configuration path uses predictable development-only credentials. To customize them, copy -`.env.example` to `.env`, replace every `change-me` value, and then add -`--env-file .env` to the command. +`.env.example` to `.env` and replace every `change-me` value. The session runner +loads the primary checkout's `.env` and keeps its backup directory when run +from a task worktree. + +Keep the foreground session open while using the app. Ctrl-C, TERM, or HUP +removes development containers, network, and the locally built application +image; the named database volume and backups remain. No development service +restarts automatically. Use `make dev-check` for a rebuild/probe/teardown and +`make dev-stop` to recover an abandoned detached stack. The Docker daemon stays +available to other projects. See the [development lifecycle](development.md). An existing zero-configuration development volume created before startup validation still has the legacy PostgreSQL password stored inside the volume. @@ -23,7 +31,7 @@ Migrate that local role once without deleting data, then start the stack again: ```bash docker compose -f deploy/compose.yaml exec postgres psql -U n2api -d n2api -v ON_ERROR_STOP=1 -c "ALTER ROLE n2api PASSWORD 'n2api-local-postgres-password'" -docker compose -f deploy/compose.yaml up -d --force-recreate +make dev ``` Do not run this fixed development-password command on a deployment with custom @@ -100,15 +108,23 @@ N2API_METRICS_PORT=9090 ``` ```bash -docker compose -f deploy/compose.yaml -f deploy/compose.metrics.yaml --env-file .env up -d +N2API_DEV_METRICS=1 make dev +``` + +Keep the foreground session open, and scrape from another terminal: + +```bash curl --fail --silent --show-error \ --header "Authorization: Bearer ${N2API_METRICS_BEARER_TOKEN}" \ http://127.0.0.1:9090/metrics ``` -Use the same override after `deploy/compose.release.yaml` for an immutable image -deployment. Publishing metrics beyond host loopback requires an explicit -`N2API_METRICS_BIND_ADDRESS` plus firewall policy; bearer authentication remains +Ctrl-C closes the metrics development session and removes its containers and +network. `make dev-stop` also recognizes older detached metrics stacks. + +Use `deploy/compose.metrics.yaml` after `deploy/compose.release.yaml` for an +immutable image deployment. Publishing metrics beyond host loopback requires +an explicit `N2API_METRICS_BIND_ADDRESS` plus firewall policy; bearer authentication remains mandatory. Do not send the bearer token over an untrusted network without a TLS reverse proxy or private encrypted transport. Missing or incorrect credentials return HTTP 401. diff --git a/docs/plans/2026-11-09-local-development-sessions.md b/docs/plans/2026-11-09-local-development-sessions.md new file mode 100644 index 00000000..3ab64e08 --- /dev/null +++ b/docs/plans/2026-11-09-local-development-sessions.md @@ -0,0 +1,47 @@ +# Local Development Sessions + +## Specification + +Local full-stack development uses `deploy/compose.yaml` only when explicitly +started for a development or verification session. All development services use +`restart: "no"`; no host boot task, timer, or Docker daemon policy is installed. +The Docker daemon remains shared host infrastructure. + +`make dev` owns the foreground session. `make dev-check` rebuilds, starts, +checks health and the bootstrap page, then exits. Both remove their development +containers, network, local application image, temporary run directory, and +unused builder cache after use. `make dev-stop` closes a leftover detached +development stack. Cleanup preserves the existing PostgreSQL volume, backups, +credentials, unrelated Docker resources, and active test runs. Disposable +isolated test volumes continue to use the existing labelled test lifecycle. + +## Implementation Plan + +1. Disable development restart policies and avoid a backup-sidecar anonymous + data volume. Leave release Compose unchanged. +2. Reuse managed test resources and signal forwarding for a session runner; + serialize ownership of the shared development project and reject containers + from release or unrelated Compose files before mutation. +3. Add Make targets and focused lifecycle checks for success, startup failure, + termination, concurrent sessions, cleanup failure, and data preservation. +4. Update startup documentation, Agent instructions, and the repository local + refresh skill so verification ends with teardown by default. +5. Keep the session lock in the runner so a forced exit permits recovery. Add + explicit metrics sessions and recognize only the base or base-plus-metrics + configuration from registered worktrees. + +## Acceptance Criteria + +- Development Compose renders every service with restart disabled. +- Foreground exit, INT, TERM, and HUP tear down owned development resources; + failed starts attempt teardown and cleanup failures return nonzero. +- A second session cannot stop an active session. Release Compose resources + are refused, and no development cleanup command deletes named volumes. +- After SIGKILL, a surviving Compose child cannot block `make dev-stop`. + `N2API_DEV_METRICS=1` selects the existing metrics override; recovery accepts + that known file combination and rejects release or unknown extra files. +- `make dev-check` passes a real no-cache rebuild and health/page probes, then + leaves no development containers or network. Existing database identity and + backup files remain intact. +- Focused lifecycle tests and Compose configuration checks pass. The exact + published diff passes local Codex review, PR CI, and target-branch CI.