lfg2025/archy
1
0
Fork 0
Code Issues 27 Pull Requests 5 Actions Packages Projects Releases 4 Wiki Activity

docs(dev-guide): package.install needs dockerImage too; helper gotchas

Browse Source 
Learned installing alby-hub/phoenixd for real: the id-only payload fails
with 'Missing dockerImage' (the store normally injects the image from the
catalog), the session helper silently reuses a stale cached session
without ARCHY_FORCE_LOGIN=1, needs jq, and its set -euo pipefail kills an
interactive shell chain without output — so the guide now wraps the flow
in a heredoc subshell.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
archipelago
2026-08-12 12:15:55 -04:00
co-authored by Claude Fable 5
parent e87e8017bf
commit b7ba35477c
1 changed files with 16 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/app-developer-guide.md
+16 -5
View File
@@ -435,21 +435,32 @@ validates every manifest on load and tells you about problems immediately
**2. Install over JSON-RPC.** **2. Install over JSON-RPC.**
The repo ships the same session helper the release lifecycle gate uses: The repo ships the same session helper the release lifecycle gate uses.
Three things to know before using it: it needs `jq`; it reuses a cached
session from `/tmp/archy-rpc-session-<uid>` unless `ARCHY_FORCE_LOGIN=1` is
set (a stale cache fails every call quietly); and it sets `set -euo pipefail`,
so run it inside a script or subshell — sourcing it into your interactive
shell makes the first failed step kill the whole chain without printing
anything.
```bash ```bash
export ARCHY_PASSWORD='<your dashboard password>' bash <<'EOF'
export ARCHY_PASSWORD='<your dashboard password>' ARCHY_FORCE_LOGIN=1
# Stock nodes serve HTTPS on 443; dev boxes behind plain nginx use: # Stock nodes serve HTTPS on 443; dev boxes behind plain nginx use:
# export ARCHY_HOST=127.0.0.1 ARCHY_SCHEME=http # export ARCHY_HOST=127.0.0.1 ARCHY_SCHEME=http
source tests/lifecycle/lib/rpc.bash source tests/lifecycle/lib/rpc.bash
rpc_login rpc_login && echo "login ok"
rpc_call package.install '{"id":"my-app"}' # Both fields are required: `dockerImage` is normally supplied by the App
# Store from the signed catalog — pre-catalog, you pass your manifest's
# image yourself (it must match, and must come from a trusted registry).
rpc_call package.install '{"id":"my-app","dockerImage":"docker.io/myorg/my-app:1.0.0"}'
EOF
``` ```
**3. Verify the lifecycle, not just the install:** **3. Verify the lifecycle, not just the install:**
```bash ```bash
rpc_call package.status '{"id":"my-app"}' # state + health rpc_call package.status '{"id":"my-app"}' # state + health (run inside the same subshell pattern)
podman ps --filter name=my-app # container is up podman ps --filter name=my-app # container is up
rpc_call package.stop '{"id":"my-app"}' # …and start, restart rpc_call package.stop '{"id":"my-app"}' # …and start, restart
sudo systemctl restart archipelago # app must survive this sudo systemctl restart archipelago # app must survive this