Dependency Management

runnem allows you to define dependencies between services, ensuring they start in the correct order and only after their dependencies are ready.

Defining Dependencies

In your runnem.yaml file, use the depends_on field to specify service dependencies:

services:
  database:
    command: cd ~/projects/myproject/database && docker-compose up
    url: postgresql://localhost:5432

  api:
    command: cd ~/projects/myproject/api && npm run dev
    url: http://localhost:3000
    depends_on: ["database"]  # api depends on database

  frontend:
    command: cd ~/projects/myproject/frontend && npm run dev
    url: http://localhost:3001
    depends_on: ["api"]  # frontend depends on api

How Dependencies Work

When you run runnem up:

1. runnem builds a dependency graph
2. Services are started in topological order
3. Each service waits for its dependencies to be ready
4. A service is considered ready when:
   • Its URL is accessible (if defined)
   • Or after a brief startup delay (if no URL is defined)

URL-Based Health Checks

For services with defined URLs, runnem will:

1. Wait for the URL to be accessible
2. Retry up to 3 times with a 2-second delay
3. Show status messages during the wait

Example with URL health checks:

services:
  database:
    command: cd ~/projects/myproject/database && docker-compose up
    url: postgresql://localhost:5432/health  # Given this health endpoint is setup in your compose file

  api:
    command: cd ~/projects/myproject/api && npm run dev
    url: http://localhost:3000/docs  # Can double as health check endpoint and handy to click on to open
    depends_on: ["database"]

Circular Dependencies

runnem detects and prevents circular dependencies:

services:
  service_a:
    command: echo "Service A"
    depends_on: ["service_b"]  # Circular dependency!

  service_b:
    command: echo "Service B"
    depends_on: ["service_a"]  # Circular dependency!

If circular dependencies are detected, runnem will:

1. Show an error message
2. List the services in the cycle
3. Prevent any services from starting

Best Practices

1. Define URLs for services when possible
2. Keep dependency chains short and simple
3. Use health check endpoints for better reliability
4. Avoid circular dependencies
5. Test your dependency configuration with runnem up