cdk/MPROCS_MODES.md

mprocs Process Management Modes

The CDK regtest environment now supports two different modes for managing processes with mprocs:

Mode 1: Log Tailing (Default)

Command: just regtest

How it works:

• Mints are started by the bash script and run in the background
• Mints write their output to log files (mintd.log)
• mprocs uses tail -f to follow these log files
• Log files persist even after mprocs exits

Pros:

• ✅ Log files are preserved for later analysis
• ✅ Simple setup
• ✅ Works even if mprocs crashes

Cons:

• ❌ Cannot restart mints from within mprocs
• ❌ Must use external commands to control mints
• ❌ mprocs shows file contents, not live processes

Mode 2: Direct Process Management

Command: just regtest-mprocs

How it works:

• mprocs directly manages the mint processes
• Mints are started/stopped by mprocs itself
• Output goes directly to mprocs (no log files by default)
• Full process control from within mprocs

Pros:

• ✅ Start/stop/restart mints directly from mprocs
• ✅ Live process output
• ✅ Better development workflow
• ✅ Process status indicators

Cons:

• ❌ Output not saved to files (unless configured)
• ❌ If mprocs crashes, you lose the processes

mprocs Controls

Direct Process Management Mode:

• Arrow keys: Navigate between processes
• s: Start the selected process
• k: Kill the selected process
• r: Restart the selected process
• Enter: Focus on a process (see its output)
• Tab: Switch between process list and output
• ?: Show help
• q: Quit mprocs (stops all managed processes)

Log Tailing Mode:

• Arrow keys: Navigate between log sources
• Enter: Focus on a log source
• Tab: Switch between process list and log view
• PageUp/PageDown: Scroll through logs
• q: Quit mprocs (processes continue running)

Usage Examples

Start with Log Tailing (Original Mode)

just regtest
# Mints start automatically and log to files
# mprocs shows log contents
# Use Ctrl+C or 'q' to exit mprocs
# Processes continue running in background

Start with Direct Process Management

just regtest-mprocs
# Only Lightning network starts automatically
# In mprocs, navigate to "cln-mint" and press 's' to start it
# Navigate to "lnd-mint" and press 's' to start it
# Use 'r' to restart mints after code changes
# Use 'q' to exit and stop all processes

Switch Between Modes

If you started with log tailing mode, you can access the direct management:

# In another terminal
source /tmp/cdk_regtest_env
just regtest-logs  # This will detect the mode and adapt

Development Workflow Comparison

Traditional (Log Tailing):

1. just regtest
2. Make code changes
3. In another terminal: just restart-mints
4. Check logs in mprocs

Direct Management:

1. just regtest-mprocs
2. Press 's' to start mints
3. Make code changes
   
4. In mprocs: press 'r' on each mint to restart
5. Watch live output directly

Technical Details

Project Root Handling

The direct process management mode ensures that:

• Startup scripts change to the correct project root directory
• Cargo commands run from where the Cargo.toml file is located
• Environment variables are properly set before starting processes

File Structure

$CDK_ITESTS_DIR/
├── start_cln_mint.sh       # Sets PROJECT_ROOT and runs cargo from there
├── start_lnd_mint.sh       # Sets PROJECT_ROOT and runs cargo from there
└── mprocs.yaml            # Points to the startup scripts

Each startup script:

1. Changes to the project root directory (cd "$PROJECT_ROOT")
2. Sets all required environment variables
3. Executes cargo run --bin cdk-mintd from the correct location

The environment variables and helper commands work the same in both modes:

• just ln-cln1 getinfo
• just btc-mine 5
• just mint-info
• etc.