Skip to content

[2026-03-08] Dev Workflow: PM2 Process Manager for Frontend + Docs

Task Metadata

  • 📆 Date: 2026-03-08
  • 🚥 Status: Complete
  • Beads Issue: 2512_genai_food_tracking-jqq (closed)

The current combined local-dev workflow still points to tmuxp:

  • Taskfile.yml exposes task dev:session and task dev:session:detached, both backed by .tmuxp.yaml
  • .tmuxp.yaml starts task dev and task docs in two panes
  • there is no checked-in PM2 ecosystem file or task pm2:* command set in the current branch
  • as of 2026-03-08, neither service is running locally:
    • frontend check failed on http://127.0.0.1:5173
    • docs check failed on http://127.0.0.1:8000

Goal: replace the combined tmuxp-based dev-session workflow with a repository-local PM2 workflow that can start, stop, inspect, and tail both the frontend and docs servers consistently across worktrees.

Key Workflow Contract

  • Keep task dev and task docs for direct one-off usage.
  • Replace only the combined session workflow (dev:session*) with PM2-backed commands.
  • Use repository-local PM2_HOME (for example .pm2/) so this repo does not collide with unrelated global PM2 processes.
  • Remove .tmuxp.yaml once PM2 replacements are verified.

Implementation Strategy

  • Add ecosystem.config.cjs at the repo root with two apps:
    • chatkcal-frontend
    • chatkcal-docs
  • Run both apps from the repository root using task-backed commands rather than ad hoc shell scripts.
  • Make the PM2-managed docs server use a fixed local port (127.0.0.1:8000) so status checks and reopen flows are deterministic.
  • Add Taskfile commands for:
    • pm2:start
    • pm2:stop
    • pm2:restart
    • pm2:status
    • pm2:logs
  • Repoint dev:session and dev:session:detached to the PM2 workflow, or replace them outright if that keeps the interface cleaner.
  • Add .pm2/ to gitignore and remove .tmuxp.yaml.

Verification Strategy

  • Start both services with the new PM2 workflow.
  • Confirm PM2 status shows both processes online.
  • Confirm HTTP responses from:
    • http://127.0.0.1:5173
    • http://127.0.0.1:8000
  • Confirm stop/restart behavior works without affecting unrelated global PM2 apps.
  • Pros: durable background workflow, simple status/log inspection, worktree-safe process state, no dependence on tmux panes or an interactive session.
  • Risks: port conflicts on 8000; PM2 command usage drift if tasks and ecosystem diverge; accidental interaction with global PM2 state.
  • Mitigations:
    • pin repo-local PM2_HOME
    • keep task commands as the user-facing entry points
    • verify start/stop/status against actual local endpoints before closing
  • Add PM2 ecosystem file for frontend and docs.
  • Add Taskfile PM2 commands and replace tmuxp session commands.
  • Remove .tmuxp.yaml.
  • Update gitignore for repo-local PM2 state.
  • Verify start, status, logs, restart, and stop flows.
  • 2026-03-08 (Approve): User approved implementation of the PM2 replacement workflow.
  • 2026-03-08 (Execute): Added ecosystem.config.cjs with repo-local PM2 apps for:
    • chatkcal-frontend
    • chatkcal-docs
  • 2026-03-08 (Execute): Added Taskfile support for:
    • dev:pm2
    • docs:pm2
    • pm2:start
    • pm2:restart
    • pm2:status
    • pm2:logs
    • pm2:stop
  • 2026-03-08 (Execute): Repointed dev:session and dev:session:detached to PM2-backed flows.
  • 2026-03-08 (Execute): Removed legacy .tmuxp.yaml and added .pm2/ to gitignore.
  • 2026-03-08 (Execute): Updated developer-facing docs to advertise the PM2 workflow.
  • 2026-03-08 (Execute): During follow-up verification, user feedback surfaced that 5173 must remain the app port for auth redirect compatibility, so the request to use distinct non-default ports was narrowed to docs only.
  • 2026-03-08 (Execute): Adjusted the implemented docs port from the originally planned 8000 to 8010 based on that execution feedback, and updated PM2/task/docs references to match the final runtime contract.
  • 2026-03-08 (Verify): Verified PM2 runtime workflow:
    • task pm2:start
    • task pm2:status
    • task pm2:restart
    • task pm2:stop
    • curl -I http://127.0.0.1:5173
    • curl -I http://127.0.0.1:8010
  • 2026-03-08 (Verify): Passed repository quality gates:
    • task lint
    • task test
  • 2026-03-08 (Review): User approved closure after confirming the PM2-managed frontend and docs servers were running successfully on 127.0.0.1:5173 and 127.0.0.1:8010.

User approval received before implementation.