Go Overlay ​
Go Overlay is a lightweight service supervisor for containers, inspired by s6-overlay. Run multiple services with dependencies, health checks, and graceful shutdown.
:material-rocket: Quick Start ​
1. Dockerfile ​
dockerfile
FROM debian:bookworm-slim
ADD https://github.com/corebunker/go-overlay/releases/latest/download/go-overlay /go-overlay
RUN chmod +x /go-overlay
COPY services.toml /services.toml
ENTRYPOINT ["/go-overlay"]2. services.toml ​
toml
[[services]]
name = "app"
command = "/app/server"
required = true
restart = "on-failure"
[services.health_check]
endpoint = "http://localhost:8080/health"
interval = 303. Build & Run ​
bash
docker build -t myapp .
docker run myapp:material-star: Features ​
| Feature | Description |
|---|---|
| Service Dependencies | depends_on + wait_after for startup ordering |
| One-shot Jobs | oneshot = true for migrations and init tasks |
| Health Checks | HTTP endpoint or command-based health monitoring |
| Restart Policies | never, on-failure, always with max attempts |
| Environment Variables | Inline env map or env_file per service |
| Graceful Shutdown | SIGTERM → wait → SIGKILL with configurable timeouts |
| CLI Management | list, status, restart via IPC socket |
| Pre/Post Scripts | Run scripts before/after service startup |
:material-book-open: Documentation ​
- LLM Reference - Complete overview with copy button for AI assistants
- Quick Reference - All config options in one page
- Boilerplate Templates - Copy-paste ready configs
- Installation - Docker, direct download, auto-install
- Configuration - Full TOML reference
- Examples - Real-world stack configurations
:material-cog: CLI Commands ​
bash
# Start supervisor (reads /services.toml)
/go-overlay
# Check service status
go-overlay list
go-overlay status
# Restart a service
go-overlay restart api:material-lightbulb: Use Cases ​
- Multiple services in a single Docker container
- Web apps with background workers
- Development environments with multiple processes
- Production containers needing reliable supervision
:material-github: Contributing ​
Contributions welcome! See Contributing Guide.
:material-license: License ​
MIT License. See LICENSE.