Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 36 additions & 45 deletions .agents/skills/n2api-local-refresh/SKILL.md
Original file line number Diff line number Diff line change
@@ -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.
37 changes: 35 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
13 changes: 12 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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:
Expand Down
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
10 changes: 6 additions & 4 deletions deploy/compose.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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}
Expand All @@ -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}
Expand All @@ -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:
Expand All @@ -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:
Expand Down
Loading
Loading