Skip to content

docs/operate/troubleshooting.md: two debugging stories on one page #60

Description

@qcentic-dev

Part of #23. Spec: ADR 0016 — The 0.1.0 shape, clauses G1.

Phase 4 — Docs and deletions
Blocked by: #37, #43, #59
Blocks: #61

What

#10's obligation, which had no destination until now: "Docs owe operators the debugging section above. 'No shell' is a support burden if it is discovered during an incident rather than read beforehand."

The page has to say two opposite things, and saying them clearly on one page is the whole job: the Panel is distroless and has no shell at allshell present → NONE, no /bin/sh, no busybox — while the Core is Ubuntu, where docker exec core bash just works.

Every Panel technique below was verified against the running prototype.

Done when

  • Panel: node is the shell — docker exec <ctr> /nodejs/bin/node -e '…' covers filesystem inspection, env dumps, HTTP probes and opening panel.db with the Panel's own better-sqlite3. Absolute path — the PATH trap applies to exec too
  • Panel: docker cp needs no shell and is daemon-side
  • Panel: a sidecar in the container's namespaces — docker run --rm -it --pid=container:<ctr> --network=container:<ctr> --cap-add=SYS_PTRACE nicolaka/netshoot — is the answer for anything needing curl, ss, strace or lsof. Note that without SYS_PTRACE namespaces still join but /proc/1/root is denied
  • Panel: gcr.io/distroless/nodejs24:debug-nonroot ships busybox at /busybox/sh and is otherwise identical — documented as the escape hatch, not the default
  • Panel: NODE_OPTIONS=--inspect=0.0.0.0:9229 works, which is strictly more than the old image offered
  • Core: docker exec core bash, docker logs, docker compose exec core actana status, and why actana start/stop/restart/logs refuse (T10)
  • The page states up front which half applies to which image, so nobody follows the Panel instructions against a Core

Decisions are locked in ADR 0016. If this ticket needs one changed, amend the ADR in the same PR — do not decide it in a comment.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions