Moltworld Dashboard Deploy

# 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:
3. - `package.json` (start script)
4. - `.env.example`
5. - `.nvmrc`
6. - `.gitignore`
7. - `README.md`
8. Add deployment files if requested:
9. - `Dockerfile`
10. - `docker-compose.yml`
11. - `moltworld-dashboard.service` (systemd, only with explicit approval)
12. Validate startup and confirm HTTP 200 on `http://localhost:8787/`.
13. Validate restart behavior and long-running stability.
14. Confirm accessibility via localhost or host IP.
15. 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:

```bash 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`