Skip to content

Go Overlay

Build Status Release License

Go Overlay is a lightweight and efficient service orchestrator written in Go, designed to run and manage multiple services within containers. Inspired by s6-overlay, it offers a modern and simple solution for process supervision with dependencies, graceful shutdown, and CLI integration.

Features

  • Multiple Service Management - Execute and monitor multiple services simultaneously
  • Dependency Management - Control the order of initialization with depends_on and wait_after
  • Graceful Shutdown - Controlled termination with configurable timeouts and signal handling
  • Health Monitoring - Automatic detection of failures and service restarts
  • CLI Integration - Command-line interface for management via IPC
  • Simple Configuration - Easy-to-read TOML files
  • Pre/Post Scripts - Execute scripts before and after service initialization
  • Circular Dependency Detection - Automatic configuration validation
  • Optimized for Containers - Lightweight, fast, and ideal for Docker environments
  • Automatic Installation - Automatic CLI installation in the system PATH

Quick Start

Installation

# Download go-overlay
ADD https://github.com/srelabz/go-overlay/releases/latest/download/go-overlay /go-overlay

# Make it executable
RUN chmod +x /go-overlay

# Copy your services configuration
COPY services.toml /services.toml

# Set go-overlay as the entrypoint
ENTRYPOINT ["/go-overlay"]

Basic Configuration

Create a services.toml file:

[timeouts]
post_script_timeout = 7
service_shutdown_timeout = 10
global_shutdown_timeout = 30
dependency_wait_timeout = 300

[[services]]
name = "web"
command = "/usr/bin/nginx"
args = ["-g", "daemon off;"]
enabled = true
required = true

[[services]]
name = "worker"
command = "/app/worker"
depends_on = "web"
wait_after = 2
enabled = true

Execution

# Start the manager (daemon)
go-overlay

# Check service status
go-overlay status

# List services
go-overlay list

# Restart a specific service
go-overlay restart web

Documentation

Explore the complete documentation to learn more about Go Overlay:

  • Installation Guide - Installation methods (GitHub, Docker, source)
  • Quick Start - Step-by-step tutorial to get started quickly
  • Configuration - Complete TOML configuration reference
  • CLI Reference - Available commands and examples of usage
  • Guides - Detailed guides on service lifecycle, shutdown, and dependencies
  • Examples - Practical examples of usage in real scenarios

Why Go Overlay?

Go Overlay was created to fill the gap between simplicity and functionality in process management within containers. Unlike complex solutions, it offers:

  • Simplicity - Intuitive configuration without steep learning curve
  • Performance - Written in Go for maximum efficiency and low overhead
  • Reliability - Robust state management and failure recovery
  • Flexibility - Support for various use cases, from simple applications to complex stacks

Use Cases

Go Overlay is ideal for:

  • Running multiple services in a single Docker container
  • Managing web applications with background workers
  • Orchestrating complete stacks (web server + database + cache)
  • Development environments with multiple processes
  • Production containers that need reliable supervision

Contributing

Contributions are welcome! Check out our contribution guide to get started.

License

Go Overlay is distributed under the MIT license. See the LICENSE file for more details.