dockside CLAUDE.md

Repo Notes

• ./test.sh runs the full static suite (Perl compile, Vue build, ESLint, StyleLint, ShellCheck, JSON/YAML, Python compile) — run it regularly, not just for Perl. ./test.sh --only <check> runs a single check (e.g. --only perl while iterating on Perl under app/server/lib or app/server/bin; --only vue, --only eslint, …).
• When validating Perl server changes on this local Dockside host, restart:
  • sudo s6-svc -t /etc/service/nginx
  • sudo s6-svc -t /etc/service/docker-event-daemon
• Before running tests that exercise server changes, restart the services above — the running server is not auto-reloaded. Rebuild the Vue bundle (cd app/client && npm run build) for client changes.

The dockside CLI

Needed for two things: running the integration suite, and ad-hoc HTTP checks against a live instance mid-session (both below). Nothing else in this repo — static checks, restarting services, editing code — needs a CLI session at all.

Session setup

Check for an existing session before assuming there isn't one or that you need credentials: run python3 cli/dockside server list (or dockside server list if it's on PATH). Recommended usage is for the developer to already be logged in as admin locally and hand that session to you, so one usually exists — never ask the user for credentials over chat. If none is found, ask the user whether they'd rather log in themselves (remind them of the login command below) or have you try it — don't just assume either way.

If asked to try it yourself: the hostname depends on your environment:

• Personal laptop/server running Dockside: www-<name>.local.dockside.dev
• Inner Dockside dev container inside an outer production Dockside: your inner container's public hostname (e.g. www-<name>.dockside-domain.com — the outer server's domain is whatever it actually is, no fixed convention to assume) — derive it rather than asking or guessing: ssl.domains[0] in /data/config/config.json gives the base domain (e.g. <name>.dockside-domain.com); prepend www- to its first label for the actual UI hostname (www-<name>.dockside-domain.com). Don't trust the container's own "Navigate to ..." boot-log line for this — confirmed unreliable: on a real instance it printed a www.<name>... form (dot, not hyphen) that 400s, while the actual working hostname was the hyphenated www-<name>... form above.