MoltWorld Dashboard Deploy

Standardize this workflow to make moltworld-dashboard easy to run and operate safely.

Runtime requirements

Required binaries:

• npm
• docker
• docker-compose

Optional (privileged persistence path only):

• systemd
• sudo

Safety gates (mandatory)

1. Treat project dependencies as untrusted until reviewed.
2. Before package install, inspect package.json and lockfile for suspicious scripts/deps.
3. Ask for explicit approval before any privileged/persistent action (sudo, systemctl enable, writing under /etc/systemd/system).
4. Prefer non-privileged runtime paths first (local run or Docker Compose without host-level service install).
5. Never use curl | bash or equivalent remote script execution.

Workflow

1. Verify baseline project files exist (server.mjs, public/).
2. Add/shareability files if missing:
   • package.json (start script)
   • .env.example
   • .nvmrc
   • .gitignore
   • README.md
3. Add deployment files if requested:
   • Dockerfile
   • docker-compose.yml
   • moltworld-dashboard.service (systemd, only with explicit approval)
4. Validate startup and confirm HTTP 200 on http://localhost:8787/.
5. Validate restart behavior and long-running stability.
6. Confirm accessibility via localhost or host IP.
7. Document runbook steps for operators.

Required file conventions

• Keep runtime state out of git (data/state.json, logs, pids).
• Keep secrets out of git (.env).
• Default runtime port: 8787.
• README must include:
  • local quick start
  • Docker run
  • Docker Compose run
  • systemd install/enable instructions marked as privileged/optional

Runtime stability checks

Use these checks when service becomes unreachable:

ss -ltnp | grep ':8787' || true
curl -I --max-time 5 http://localhost:8787/

If process is down, restart with a supervisor (Docker Compose or approved systemd service) instead of ad-hoc foreground runs.

Troubleshooting quick checks

• Service down: verify listener on :8787.
• Loop timeouts: increase API timeout and add retries in postJson.
• Process died after exec session: restart with supervisor.

References

• Deployment/runbook command snippets: references/commands.md