# Process Compose — Orchestrate Non-Containerized Processes

> Process Compose is a Docker Compose-like tool for managing multiple local processes with dependency ordering, health checks, and a TUI dashboard.

## Install

Save in your project root:

# Process Compose — Orchestrate Non-Containerized Processes

## Quick Use
```bash
# Install
brew install f1bonacc1/tap/process-compose
# or: go install github.com/F1bonacc1/process-compose@latest

# Create a process-compose.yaml
cat > process-compose.yaml << EOF
version: "0.5"
processes:
  frontend:
    command: "npm run dev"
    working_dir: "./web"
  backend:
    command: "go run ./cmd/server"
    depends_on:
      database:
        condition: process_healthy
  database:
    command: "docker compose up postgres"
    readiness_probe:
      exec:
        command: "pg_isready -h localhost"
      period_seconds: 5
EOF

# Start all processes
process-compose up
```

## Introduction
Process Compose brings Docker Compose semantics to bare-metal processes. It lets you define, order, and monitor multiple local services in a single YAML file with dependency graphs, health checks, and restart policies. A built-in TUI or web UI shows real-time status, logs, and controls — without requiring containers.

## What Process Compose Does
- Manages multiple local processes defined in a `process-compose.yaml` file
- Supports dependency ordering with health check conditions before starting dependents
- Provides readiness and liveness probes (exec, HTTP, or TCP)
- Includes a terminal UI dashboard showing status, logs, and restart controls per process
- Offers a REST API and optional web UI for remote monitoring

## Architecture Overview
Process Compose is a single Go binary that parses the YAML config, builds a dependency DAG, and starts processes in topological order. Each process runs as a child with captured stdout/stderr streams. A health-check scheduler polls readiness probes and updates the dependency state machine. The TUI layer renders a process list with live status indicators and scrollable log output. An embedded HTTP server optionally exposes a REST API and web dashboard.

## Self-Hosting & Configuration
- Install via Homebrew, Go install, Nix, or download a prebuilt binary
- Define services in `process-compose.yaml` at the project root
- Configure per-process environment variables, working directories, and restart policies
- Use readiness probes to gate dependent processes until backends are ready
- Enable the web UI with `--port 8080` for browser-based monitoring

## Key Features
- Docker Compose-style YAML for defining local multi-service development environments
- Dependency graph with health check gating ensures correct startup ordering
- Built-in TUI with per-process log streaming, restart, and stop controls
- REST API and web UI for remote monitoring of long-running process sets
- Namespace support for running subsets of processes from the same config file

## Comparison with Similar Tools
- **Docker Compose** — Container-focused; Process Compose manages bare processes
- **mprocs** — Simpler multi-process TUI, no dependency ordering or health checks
- **Foreman / Overmind** — Procfile-based with interleaved output, no dependency graph
- **Tilt** — Kubernetes-centric development tool with live update, heavier setup
- **just + background jobs** — Manual scripting approach, no monitoring or health checks

## FAQ
**Q: How does this differ from Docker Compose?**
A: Process Compose manages native OS processes, not containers. No Docker daemon is required. It is ideal when containerizing every service adds unnecessary overhead.

**Q: Can I define dependencies between processes?**
A: Yes. Use `depends_on` with `condition: process_healthy` or `process_completed_successfully` to order startup based on health probe results.

**Q: Does it support auto-restart on crash?**
A: Yes. Set `restart: on_failure` or `restart: always` per process to enable automatic restarts with configurable backoff.

**Q: Can I run only a subset of services?**
A: Yes. Use `process-compose up frontend backend` to start named processes, or define namespaces to group related services.

## Sources
- https://github.com/F1bonacc1/process-compose
- https://f1bonacc1.github.io/process-compose/

---
Source: https://tokrepo.com/en/workflows/process-compose-orchestrate-non-containerized-processes-f7cc92f8
Author: AI Open Source