Skip to content

Latest commit

 

History

History
296 lines (214 loc) · 7.67 KB

deployment.md

File metadata and controls

296 lines (214 loc) · 7.67 KB

CCEM Deployment Guide

Prerequisites

  • Node.js >= 18.0.0 (for CCEM core TypeScript components)
  • Elixir >= 1.14 with OTP >= 25 (for APM v4 Phoenix server)
  • Python 3.x (for APM v3 fallback, optional)
  • jq (used by session_init.sh for JSON manipulation)

APM v4 Phoenix Server

First-Time Setup

cd ~/Developer/ccem/apm-v4
mix deps.get
mix compile

Starting the Server

cd ~/Developer/ccem/apm-v4
mix phx.server

The server starts on port 3032. Open http://localhost:3032 to access the dashboard.

Automatic Startup via Hooks

In normal operation, you do not need to start the server manually. The session_init.sh hook automatically starts it when a Claude Code session begins:

  1. Claude Code fires the SessionStart hook
  2. session_init.sh checks if port 3032 is occupied
  3. If not, it runs mix phx.server in the background with output redirected to ~/Developer/ccem/apm/hooks/apm_server.log
  4. PID is written to ~/Developer/ccem/apm-v4/.apm.pid
  5. The hook waits 3 seconds for the server to initialize, then confirms via port check

Stopping the Server

# Via PID file
kill $(cat ~/Developer/ccem/apm-v4/.apm.pid)

# Or find the process
lsof -ti:3032 | xargs kill

Running Tests

cd ~/Developer/ccem/apm-v4
mix test

Expected output: 233 tests, 0 failures.

Session Registration Flow

When a new Claude Code session starts:

1. Claude Code fires SessionStart hook
         |
2. session_init.sh receives JSON payload (session_id, cwd)
         |
3. Derives project_name from basename of cwd
         |
4. Checks if APM server is running (PID file + port check)
   |                    |
   | (not running)      | (running)
   v                    v
5a. Starts Phoenix    5b. Skip
         |
6. Writes ~/Developer/ccem/apm/sessions/{session_id}.json
         |
7. Upserts project into apm_config.json:
   - If project exists: append session to sessions array
   - If new project: add to projects array with session
   - Updates active_project to current project name
         |
8. POST http://localhost:3032/api/config/reload
         |
9. APM server re-reads config, discovers new session
         |
10. Dashboard updates in real-time via PubSub/LiveView

Multi-Project Setup

APM v4 supports monitoring multiple projects simultaneously through a single server instance.

How Projects Get Registered

Projects are registered automatically when a Claude Code session starts in their directory. No manual configuration is needed. The session_init.sh hook handles everything:

  • Opening a Claude Code session in /Users/jeremiah/Developer/ccem registers a project named ccem
  • Opening a session in /Users/jeremiah/tools/@yj/lfg registers a project named lfg
  • Each subsequent session in the same directory appends to the existing project's sessions array

Viewing Projects

  • Landing page (http://localhost:3032): Shows a card grid of all registered projects with session counts, agent counts, and Ralph progress.
  • Project dashboard (http://localhost:3032/project/{name}/): Shows the full dashboard scoped to a single project (v3 Python server route).
  • All Projects LiveView (http://localhost:3032/apm-all): Phoenix LiveView overview of all projects (v4).

Switching Active Project

The active_project field in apm_config.json determines which project is shown by default. It is automatically updated when a new session starts. You can also switch manually:

# Via API
curl -X POST http://localhost:3032/api/config/reload

# Or edit apm_config.json directly and reload
jq '.active_project = "my-project"' ~/Developer/ccem/apm/apm_config.json > /tmp/cfg.json && \
  mv /tmp/cfg.json ~/Developer/ccem/apm/apm_config.json && \
  curl -X POST http://localhost:3032/api/config/reload

Project Scoping in API Calls

Most API endpoints accept ?project=<name> to scope data to a specific project:

# Get data for a specific project
curl http://localhost:3032/api/data?project=ccem

# Discover agents for a specific project
curl http://localhost:3032/api/agents/discover?project=lfg

CCEM Core (TypeScript)

Installation

cd ~/Developer/ccem
npm install

Building

npm run build

Running the CLI

# Via npm script
npx ccem tui

# Or after global install
npm install -g .
ccem merge --strategy recommended --config ./proj1/.claude ./proj2/.claude

Running Tests

npm test                # Run all tests
npm run test:coverage   # With coverage report
npm run typecheck       # Type checking only
npm run lint            # Linting

APM v3 Python Server (Fallback)

The Python v3 server can be used as a fallback if Elixir is not available:

cd ~/Developer/ccem/apm
python3 monitor.py

This serves the same dashboard on port 3032 with identical API endpoints. The v3 server reads the same apm_config.json and supports the v4 multi-project format with backward compatibility for the v3 flat format.

Web UI

cd ~/Developer/ccem
npm run ui:dev      # Development server
npm run ui:build    # Production build
npm run ui:test     # Run UI tests

CCEMAgent (SwiftUI)

A native macOS menubar application at ~/Developer/ccem/CCEMAgent/. Build and launch:

cd ~/Developer/ccem/CCEMAgent
swift build -c release
open -a CCEMAgent

Features:

  • Connection state indicator (connected / connecting / disconnected)
  • Project count and active session display
  • Start/Stop APM server from disconnected state
  • Telemetry usage chart
  • Background task monitor with logs
  • Docker socket repair
  • Launch at login toggle

Troubleshooting

Server won't start

# Check if port is in use
lsof -ti:3032

# Check the log
tail -50 ~/Developer/ccem/apm/hooks/apm_server.log

# Check Elixir deps
cd ~/Developer/ccem/apm-v4 && mix deps.get

Sessions not appearing in dashboard

# Check hook log
tail -20 ~/Developer/ccem/apm/hooks/apm_hook.log

# Check config was updated
cat ~/Developer/ccem/apm/apm_config.json | jq '.projects | length'

# Manually trigger reload
curl -X POST http://localhost:3032/api/config/reload

Docker Socket Repair

Docker Desktop on macOS can lose its socket symlink after crashes. CCEM includes built-in repair tools.

Symptoms:

  • docker info returns "Cannot connect to the Docker daemon"
  • Docker Desktop shows "Engine running" but containers show errors
  • ls ~/.docker/run/docker.sock returns "No such file"

Fix via Claude Code skill:

/docksock              # Auto-detect and repair
/docksock status       # Check socket health
/docksock restart      # Full Docker restart + repair

Fix via CLI:

ccem docksock status   # Check health
ccem docksock repair   # Auto-repair
ccem docksock restart  # Full restart

Fix via CCEMAgent: The menubar app shows "Repair Docker Socket" when the socket is broken. Click to auto-repair.

Manual fix:

ln -sf ~/Library/Containers/com.docker.docker/Data/docker.raw.sock ~/.docker/run/docker.sock

See Docker Socket Repair wiki page for full details.

APM commands

The /ccem apm slash command provides management operations:

Command Description
/ccem apm init Initialize/re-register current session
/ccem apm start Start APM server
/ccem apm stop Stop APM server
/ccem apm open Open dashboard in browser
/ccem apm restart Restart APM server
/ccem apm refresh Reload config
/ccem apm status Show server status
/ccem apm manage all Show all management info
/ccem apm manage sessions List sessions
/ccem apm manage cleanup Clean stale sessions