Quick Start¶

This guide will walk you through setting up and running your first services with Go Overlay.

Prerequisites¶

Go Overlay installed (Installation Guide)
Basic understanding of TOML configuration format

Step 1: Create a Configuration File¶

Create a configuration file at /services.toml:

# Create the configuration directory
sudo mkdir -p /etc/go-overlay

# Create the configuration file
sudo nano /services.toml

Step 2: Define Your Services¶

Add a basic service configuration to services.toml:

# Global timeout settings (optional)
[timeouts]
service_shutdown_timeout = 10
global_shutdown_timeout = 30

# Define your first service
[[services]]
name = "web-server"
command = "/usr/bin/python3"
args = ["-m", "http.server", "8080"]
enabled = true
required = false

# Define a second service
[[services]]
name = "background-worker"
command = "/usr/local/bin/worker"
args = ["--config", "/etc/worker/config.yml"]
enabled = true
required = false

Service Configuration

name: Unique identifier for the service
command: Path to the executable
args: Command-line arguments as an array
enabled: Whether the service should start automatically
required: If true, system shuts down when this service fails

Step 3: Start the Daemon¶

Run go-overlay in daemon mode to start all enabled services:

# Start in foreground (useful for testing)
go-overlay daemon

# Or run in background
go-overlay daemon &

Expected output:

[INFO] Starting go-overlay daemon
[INFO] Loading configuration from /services.toml
[INFO] Starting service: web-server
[INFO] Starting service: background-worker
[INFO] Service web-server is RUNNING (PID: 1234)
[INFO] Service background-worker is RUNNING (PID: 1235)
[INFO] All services started successfully

Step 4: Manage Your Services¶

Once the daemon is running, use the CLI to manage services:

Check Service Status¶

go-overlay status

Output:

SERVICE              STATUS    PID     UPTIME
web-server          RUNNING   1234    2m 30s
background-worker   RUNNING   1235    2m 30s

List All Services¶

go-overlay list

Restart a Service¶

go-overlay restart web-server

Stop the Daemon¶

To gracefully stop all services and the daemon:

# Send SIGTERM to the daemon process
kill -TERM <daemon-pid>

# Or use pkill
pkill -TERM go-overlay

Complete Example¶

Here's a complete example with a web application stack:

[timeouts]
service_shutdown_timeout = 10
global_shutdown_timeout = 30
dependency_wait_timeout = 30

# Redis cache
[[services]]
name = "redis"
command = "/usr/bin/redis-server"
args = ["--port", "6379"]
enabled = true
required = true

# Web application
[[services]]
name = "webapp"
command = "/app/server"
args = ["--port", "8080"]
enabled = true
required = true
depends_on = ["redis"]
wait_after = 2

# Background job processor
[[services]]
name = "worker"
command = "/app/worker"
enabled = true
required = false
depends_on = ["redis"]

This configuration:

Starts Redis first (required service)
Waits 2 seconds, then starts the web application
Starts the background worker after Redis is running
If Redis fails, the entire system shuts down (required = true)

Troubleshooting¶

Service Won't Start¶

Common Issues

Command not found: Verify the command path is correct
Permission denied: Ensure the binary has execute permissions
Port already in use: Check if another process is using the port

Check the logs for detailed error messages:

# View daemon logs (if logging to file)
tail -f /var/log/go-overlay.log

# Or check system logs
journalctl -u go-overlay -f

Service Keeps Restarting¶

If a service continuously restarts:

Check if the command is valid and executable
Verify all dependencies are available
Review the service's own logs for errors
Ensure required files and configurations exist

# Check service status
go-overlay status

# Manually test the command
/path/to/command --args

Daemon Not Responding¶

If the CLI commands don't work:

IPC Communication

The CLI communicates with the daemon via IPC. Ensure:

The daemon is actually running: ps aux | grep go-overlay
IPC socket is accessible (usually in /tmp or /var/run)
You have permissions to access the socket

Configuration Errors¶

If the daemon fails to start:

Validate your TOML syntax:

# Use a TOML validator or check manually
cat /services.toml

Common TOML mistakes:
Missing quotes around strings with special characters
Incorrect array syntax (use [] not ())
Duplicate service names

Next Steps¶

Now that you have go-overlay running: