forked from retoor/devplacepy
Add community node protocol spec, Agent Skills, and make the failing tests hermetic
Community nodes (Phase 1 of plan.md): the protocol specification in services/nodes/spec.py as the single source of truth, GET /nodes/spec.json, a generated protocol docs page, the Community nodes API docs group, and the implementation plan plus the residential proxy research. The no-open-proxy rule is enforced in the spec (open_proxy cannot be set). Agent Skills: register the Skills API docs group, cascade skills on account deletion, add the nested CLAUDE.md, README and routes docs, and cover the parser, the fetcher (end to end against a mock origin), the data layer and the routes with 73 unit and 16 api tests. Tests made hermetic with the repo's existing patterns instead of ambient environment: embeddings tests set OPENROUTER_API_KEY via monkeypatch, the workspace tests install FakeBackend via runtime.set_backend, and the skills install tests use run_async. DockerCliBackend now returns 127 (command not found) when the CLI is missing instead of raising FileNotFoundError, so a host without docker answers with a clean error rather than a 500. The Providers tab empty state no longer names the Model routes tab. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# Podman deployment (rootless, no docker daemon)
|
||||
|
||||
Hosts without a docker daemon (like `devplace`) run the stack with the Python
|
||||
`podman-compose` plus the `docker-compose.podman.yml` overlay. The base
|
||||
`docker-compose.yml` is unchanged and stays the file rootful `docker compose`
|
||||
uses; the overlay only adjusts what rootless podman needs.
|
||||
|
||||
## Commands
|
||||
|
||||
Always go through the make targets - they pin both `-f` files. A bare
|
||||
`podman-compose up -d` drops the overlay and recreates a crashing app (see
|
||||
"Why the overlay exists").
|
||||
|
||||
```bash
|
||||
make podman-build # build images (only when pyproject/Dockerfiles change)
|
||||
make podman-up # start (also warns if user linger is off)
|
||||
make podman-reload # restart workers on new code (bind-mounted, no rebuild)
|
||||
make podman-ps # container status
|
||||
make podman-logs # tail output
|
||||
make podman-down # stop
|
||||
```
|
||||
|
||||
Open `http://<host>:${PORT}` (default 10500, published on 127.0.0.1 for the
|
||||
front proxy). Source-only changes need just `make podman-reload`.
|
||||
|
||||
## Why the overlay exists
|
||||
|
||||
The base file runs the app as `user: 1000:1000`, which is correct for rootful
|
||||
docker (container uid 1000 == host uid 1000). Under **rootless** podman the
|
||||
default userns instead maps container uid 1000 to a subordinate host uid
|
||||
(100999), which cannot write the bind-mounted checkout (owned by host uid
|
||||
1000) - uvicorn dies on startup with
|
||||
`PermissionError: ... '/app/data/locks/devplace-init.lock'`, the app never
|
||||
turns healthy, and nginx (which waits on `service_healthy`) never starts.
|
||||
|
||||
The overlay sets `user: "0:0"` for the app: container root maps back to the
|
||||
invoking host user under rootless, restoring write access while staying
|
||||
unprivileged on the host. (`userns_mode: keep-id` would also fix the mapping
|
||||
but podman rejects `--userns` together with `--pod`, and podman-compose puts
|
||||
all services in one pod.)
|
||||
|
||||
## One compose tool only
|
||||
|
||||
Use the Python `podman-compose` (`/usr/bin/podman-compose`) for this stack,
|
||||
never mix it with native `podman compose` in the same project directory. They
|
||||
use different container names (`devplace_app_1` vs `devplace-app-1`) and would
|
||||
create a second stack fighting over port 10500.
|
||||
|
||||
## Surviving reboots
|
||||
|
||||
Both services use `restart: unless-stopped`, but rootless containers only
|
||||
restart after a reboot if the host user's systemd linger is enabled:
|
||||
|
||||
```bash
|
||||
loginctl show-user "$(id -un)" | grep Linger # want: Linger=yes
|
||||
sudo loginctl enable-linger "$(id -un)" # fix if off
|
||||
```
|
||||
|
||||
`make podman-up` prints a warning when linger is off.
|
||||
|
||||
## Known differences from docker
|
||||
|
||||
- The admin-only **Container Manager** needs the docker socket, which does not
|
||||
exist on podman hosts. The `[containers] docker ps failed: [Errno 2]` lines
|
||||
in the app log are expected noise, not an error; serving the site is
|
||||
unaffected.
|
||||
- `make docker-attach` / the containers overlay do not apply here.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- `PermissionError ... /app/data/...` on boot: the app was (re)created
|
||||
without the overlay. Run `make podman-up` (it recreates with the fix).
|
||||
- `up` hangs with no output: it is waiting on the app healthcheck. In another
|
||||
shell run `podman logs devplace_app_1` - a crash loop there is the cause.
|
||||
- `Error: --userns and --pod cannot be set together`: a `userns_mode`
|
||||
override is in play; remove it, this stack relies on `user: "0:0"`.
|
||||
- Port 10500 already in use: a second stack (other compose tool, or bare-metal
|
||||
`make prod`) is running. `podman ps -a` plus `ss -tlnp` show the conflict.
|
||||
Reference in New Issue
Block a user