Services Configuration¶

Services are the core of Go Overlay configuration. Each service represents a process that Go Overlay will manage, including starting, monitoring, and stopping.

Service Definition Structure¶

Services are defined as TOML table arrays using the [[services]] syntax. Each service block defines one managed process:

[[services]]
name = "my-service"
command = "/path/to/executable"
args = ["--option", "value"]
enabled = true

Service Fields Reference¶

Required Fields¶

name¶

Type: string
Required: Yes

Unique identifier for the service. Used in logs, CLI commands, and dependency references.

[[services]]
name = "web-server"

command¶

Type: string
Required: Yes

Full path to the executable to run. Can be an absolute path or a command available in PATH.

[[services]]
command = "/usr/sbin/nginx"

Optional Fields¶

args¶

Type: array of strings
Default: []

Command-line arguments passed to the service executable.

[[services]]
args = ["-g", "daemon off;", "-c", "/etc/nginx/nginx.conf"]

pre_script¶

Type: string
Default: None

Path to a script that runs before starting the service. Useful for initialization tasks like database migrations or configuration generation.

[[services]]
pre_script = "/scripts/init-database.sh"

Note

If the pre_script fails (non-zero exit code), the service will not start.

pos_script¶

Type: string
Default: None

Path to a script that runs after the service starts. Useful for verification, health checks, or post-startup configuration.

[[services]]
pos_script = "/scripts/verify-service.sh"

Warning

The pos_script is subject to the post_script_timeout setting. If it doesn't complete within the timeout, it will be terminated.

user¶

Type: string
Default: Current user

User account to run the service as. Useful for security isolation and running services with minimal privileges.

[[services]]
user = "www-data"

Tip

Running services as non-root users is a security best practice. Ensure the user has necessary permissions for the service's files and directories.

enabled¶

Type: boolean
Default: true

Whether the service should be started. Set to false to disable a service without removing its configuration.

[[services]]
enabled = false

required¶

Type: boolean
Default: false

Whether the service is critical to system operation. If a required service fails, Go Overlay will initiate a graceful shutdown of all services.

[[services]]
required = true

Critical Services

Use required = true only for services that are essential for your application. Failure of a required service will trigger system shutdown.

depends_on¶

Type: array of strings
Default: []

List of service names that must be started before this service. Ensures proper startup ordering.

[[services]]
depends_on = ["database", "cache"]

See Advanced Configuration for more details on dependency management.

wait_after¶

Type: integer (seconds)
Default: 0

Number of seconds to wait after starting this service before starting dependent services. Useful when a service needs time to initialize.

[[services]]
wait_after = 5

Field Reference Table¶

Field	Type	Required	Default	Description
`name`	string	Yes	-	Unique service identifier
`command`	string	Yes	-	Path to executable
`args`	array	No	`[]`	Command-line arguments
`pre_script`	string	No	-	Script to run before service starts
`pos_script`	string	No	-	Script to run after service starts
`user`	string	No	current user	User to run service as
`enabled`	boolean	No	`true`	Whether to start the service
`required`	boolean	No	`false`	Whether failure triggers system shutdown
`depends_on`	array	No	`[]`	Services this depends on
`wait_after`	integer	No	`0`	Seconds to wait after starting

Real-World Examples¶

Nginx Web Server¶

[[services]]
name = "nginx"
command = "/usr/sbin/nginx"
args = ["-g", "daemon off;"]
user = "www-data"
enabled = true
required = true

MariaDB Database¶

[[services]]
name = "mariadb"
command = "/usr/bin/mysqld"
args = ["--datadir=/var/lib/mysql", "--user=mysql"]
pre_script = "/scripts/init-mysql.sh"
user = "mysql"
enabled = true
required = true
wait_after = 10

Node.js Application¶

[[services]]
name = "node-app"
command = "/usr/bin/node"
args = ["/app/server.js"]
depends_on = ["mariadb", "redis"]
user = "node"
enabled = true
required = true

PHP-FPM¶

[[services]]
name = "php-fpm"
command = "/usr/sbin/php-fpm"
args = ["--nodaemonize", "--fpm-config", "/etc/php/8.2/fpm/php-fpm.conf"]
user = "www-data"
enabled = true
required = false

FastAPI Application¶

[[services]]
name = "fastapi"
command = "/usr/local/bin/uvicorn"
args = ["main:app", "--host", "0.0.0.0", "--port", "8000"]
pre_script = "/app/migrations/run.sh"
pos_script = "/app/healthcheck.sh"
depends_on = ["postgres", "redis"]
wait_after = 3
user = "app"
enabled = true
required = true

Complete Multi-Service Example¶

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

# Database
[[services]]
name = "postgres"
command = "/usr/lib/postgresql/15/bin/postgres"
args = ["-D", "/var/lib/postgresql/data"]
pre_script = "/scripts/init-postgres.sh"
user = "postgres"
enabled = true
required = true
wait_after = 5

# Cache
[[services]]
name = "redis"
command = "/usr/bin/redis-server"
args = ["/etc/redis/redis.conf"]
user = "redis"
enabled = true
required = false

# Background Worker
[[services]]
name = "celery-worker"
command = "/app/venv/bin/celery"
args = ["-A", "tasks", "worker", "--loglevel=info"]
depends_on = ["redis", "postgres"]
user = "app"
enabled = true
required = false

# Web Application
[[services]]
name = "web-app"
command = "/app/venv/bin/gunicorn"
args = ["app:app", "--bind", "0.0.0.0:8000", "--workers", "4"]
depends_on = ["postgres", "redis"]
pre_script = "/app/migrate.sh"
pos_script = "/app/warmup.sh"
user = "app"
enabled = true
required = true
wait_after = 2

# Reverse Proxy
[[services]]
name = "nginx"
command = "/usr/sbin/nginx"
args = ["-g", "daemon off;"]
depends_on = ["web-app"]
user = "www-data"
enabled = true
required = true

Service Naming Conventions¶

Good service names are:

Descriptive: Clearly indicate what the service does
Unique: No duplicates in the configuration
Lowercase: Use lowercase with hyphens for multi-word names
Concise: Short but meaningful

Examples: - ✅ web-server, database, cache, worker - ❌ service1, app, s, my_really_long_service_name_that_is_too_verbose

Common Patterns¶

Database with Initialization¶

[[services]]
name = "database"
command = "/usr/bin/mysqld"
pre_script = "/scripts/init-db.sh"
user = "mysql"
required = true
wait_after = 10

Service with Health Check¶

[[services]]
name = "api"
command = "/app/api-server"
pos_script = "/scripts/health-check.sh"
required = true

Optional Background Service¶

[[services]]
name = "metrics-collector"
command = "/usr/bin/prometheus"
enabled = true
required = false  # System can run without metrics

Service with User Switching¶

[[services]]
name = "app"
command = "/app/server"
user = "appuser"  # Run as non-root for security
required = true