Usage in Practice

This guide covers practical scenarios and real-world examples of using runnem effectively.

Project Structure

Each project has its own root-level runnem configuration:

~/projects/
├── project-a/
│   ├── runnem.yaml
│   ├── frontend/
│   └── api/
└── project-b/
    ├── runnem.yaml
    ├── auth-service/
    └── data-service/

Switching Between Projects

runnem makes it easy to switch between different projects:

# Start working on Project A
cd ~/projects/project-a
runnem up    # Starts all services in project-a

# Need to check something in Project B
cd ~/projects/project-b
runnem up    # Error: Services already running
             # Please run 'runnem down' first
runnem down  # Stop existing services
runnem up    # Now successfully starts Project B services

# Back to Project A
cd ~/projects/project-a
runnem up    # Error: Services already running
             # Please run 'runnem down' first
runnem down  # Stop Project B services
runnem up    # Now successfully starts Project A services
runnem list  # Shows status of project-a services

Common Workflows

Quick Context Switching

When you need to switch between projects frequently:

# Working on Project A
cd ~/projects/project-a
runnem up

# Need to check Project B
runnem -p ~/projects/project-b up    # May prompt for down first
runnem -p ~/projects/project-b down  # If needed
runnem -p ~/projects/project-b up    # Then up again
# Project B services start up
# Do what you need to do
runnem -p ~/projects/project-b down

# Back to Project A
runnem -p ~/projects/project-a up    # May prompt for down first
runnem -p ~/projects/project-a down  # If needed
runnem -p ~/projects/project-a up    # Then up again

Parallel Development

Working on multiple projects simultaneously:

# Start Project A services
cd ~/projects/project-a
runnem up

# In another terminal, work on Project B
cd ~/projects/project-b
runnem up    # May prompt for down first
runnem down  # If needed
runnem up    # Then up again

# Both projects' services run independently

Best Practices

1. Project Organization

   • Keep one runnem.yaml at the root of each project
   • Use clear project names
   • Document service relationships within each project

2. Service Management

   • Follow runnem's prompts to run down before up when needed
   • Use -p flag when managing services from outside project directory
   • Keep services running only when needed
   • Use runnem down when switching projects to free resources

3. Development Workflow

   • Use consistent project structures
   • Document project-specific requirements
   • Keep configurations in version control

Troubleshooting

Common issues and solutions:

1. Service Conflicts

   • Follow runnem's prompts to run down before up
   • Check for port conflicts between projects
   • Verify services are running in correct project
   • Use runnem list to check service status

2. Resource Management

   • Monitor system resources across projects
   • Clean up unused services with runnem down
   • Use appropriate port assignments per project