Usage in Practice

This guide covers practical scenarios and real-world examples of using runnem effectively. The assumtion is that ports between projects are going to overlap, so instead of trying to run projects simultaneously, runnem makes it quick to switch between running projects.

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

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