systemg

Table of Contents

1. Getting Started
   • 1.1 Installation
   • 1.2 Running a Basic Start Command
2. Why systemg
   • 2.1 Features
   • 2.2 Comparison
3. Development
   • 3.1 Testing
   • 3.2 Build from Source
   • 3.3 Contributing

---

Systemg - A Lightweight Process Manager

Systemg is a simple, fast, and dependency-free process manager written in Rust. It aims to provide a minimal alternative to systemd and other heavyweight service managers, focusing on ease of use, clarity, and performance.

---

Getting Started

Installation

Install the system binary:

$ curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh

Install systemg using cargo:

$ cargo install sysg

Or download the pre-built binary from the releases page.

Running a Basic Start Command

Start the process manager with the default configuration:

# Start with default configuration file (systemg.yaml)
$ sysg start

# Start with a specific configuration file
$ sysg start --config systemg.yaml

# Start the long-lived supervisor (persists after you log out)
$ sysg start --config systemg.yaml --daemonize

When the supervisor is running it remains active in the background, holding service processes in the same process group so commands like sysg stop, sysg restart, sysg status, and sysg logs can coordinate them even after you disconnect from the shell that started them.

---

Why systemg

Traditional process managers like systemd are complex, heavy, and introduce unnecessary dependencies. Systemg offers a lightweight, configuration-driven solution that's easy to set up and maintain.

Features

• Declarative YAML Configuration - Define services, dependencies, and restart policies easily.
• Automatic Process Monitoring - Restart crashed services based on custom policies.
• Dependency-Aware Startup - Honour depends_on chains, skip unhealthy dependencies, and cascade stop dependents on failure.
• Environment Variable Support - Load variables from .env files and per-service configurations.
• Rolling Deployments - Orchestrate zero-downtime restarts with pre-start commands, health probes, and grace periods.
• Lifecycle Webhooks - Trigger outbound notifications or remediation scripts on start/stop/restart outcomes with per-hook timeouts. See Webhooks documentation.
• Cron Scheduling - Run short-lived, recurring tasks on a cron schedule with overlap detection and execution history.
• Minimal & Fast - Built with Rust, designed for performance and low resource usage.
• No Root Required - Unlike systemd, it doesn't take over PID 1.

Dependency Handling

Declare service relationships with the depends_on field to coordinate startup order and health checks. Systemg will:

• start services in a topologically sorted order so each dependency is running or has exited successfully before its dependents launch;
• skip dependents whose prerequisites fail to start, surfacing a clear dependency error instead of allowing a partial boot;
• stop running dependents automatically when an upstream service crashes, preventing workloads from running against unhealthy backends.

For example:

version: "1"
services:
  database:
    command: "postgres -D /var/lib/postgres"

  web:
    command: "python app.py"
    depends_on:
      - database

If database fails to come up, web will remain stopped and log the dependency failure until the database is healthy again.

Rolling Deployments

Services can opt into rolling restarts so existing instances keep serving traffic until replacements are healthy. Add a deployment block to configure the behaviour:

version: "1"
services:
  api:
    command: "./target/release/api"
    restart_policy: "always"
    deployment:
      strategy: "rolling"          # default is "immediate"
      pre_start: "cargo build --release"
      health_check:
        url: "http://localhost:8080/health"
        timeout: "60s"
        retries: 5
      grace_period: "5s"

• strategy — set to rolling to enable the zero-downtime workflow, or omit to keep the traditional stop/start cycle.
• pre_start — optional shell command executed before the new instance launches (perfect for build or migrate steps).
• health_check — optional HTTP probe the replacement must pass before traffic flips; configure timeout and retry budget per service.
• grace_period — optional delay to keep the old instance alive after the new one passes health checks, giving load balancers time to rebalance.

If any rolling step fails, systemg restores the original instance and surfaces the error so unhealthy builds never replace running services.

Cron Scheduling

Services can be configured to run on a cron schedule for short-lived, recurring tasks. Cron jobs are managed by the supervisor and run independently of regular services:

version: "1"
services:
  backup:
    command: "sh backup-script.sh"
    cron:
      expression: "0 0 * * * *"  # Run every hour at minute 0
      timezone: "America/New_York"  # Optional, defaults to system timezone

Key features:

• Standard cron syntax - Uses 6-field cron expressions (second, minute, hour, day, month, day of week).
• Overlap detection - If a cron job is scheduled to run while a previous execution is still running, the new execution is skipped and an error is logged.
• Execution history - The last 10 executions are tracked with their start time, completion time, and status.
• Service separation - A service cannot have both a command for continuous running and a cron configuration; cron is opt-in via the cron field.

Note: Cron jobs do not support restart policies, as they are designed to be short-lived tasks that complete and exit.

Additional Commands

The sysg command-line interface provides several subcommands for managing processes:

Stop - Stop the process manager or a specific service:

# Stop the supervisor and every managed service
$ sysg stop

# Stop a specific service
$ sysg stop --service myapp

Restart - Restart the process manager:

# Restart all services managed by the supervisor
$ sysg restart

# Restart a specific service
$ sysg restart -s myapp

# Restart with a different configuration
$ sysg restart --config new-config.yaml

Status - Check the status of running services:

# Show status of all services
$ sysg status

# Show status of a specific service
$ sysg status --service webserver

Logs - View logs for a specific service:

# View the last 50 lines of logs for all services
$ sysg logs

# View logs for a specific service
$ sysg logs api-service

# View a custom number of log lines
$ sysg logs database --lines 100

Log Level - Override logging verbosity:

# Override logging verbosity for the current run (works with every subcommand; names or 0-5)
$ sysg start --log-level debug
$ sysg start --log-level 4

Comparison

Feature	Systemg	systemd	Supervisor	Docker Compose
Lightweight	Yes	No (Heavy)	No (Python)	No (Containers)
No Dependencies	Yes	No (DBus, etc.)	No (Python)	No (Docker)
Simple Config	YAML	Complex Units	INI	YAML
Process Monitoring	Yes	Yes	Yes	Yes
PID 1 Required?	No	Yes	No	No
Handles Dependencies?	Yes	Yes	No	Yes

---

Development

Testing

To run the test suite:

# Run all tests
$ cargo test

# Run specific test
$ cargo test test_service_lifecycle

Build from Source

To build systemg from source:

# Clone the repository
$ git clone https://github.com/ra0x3/systemg.git
$ cd systemg

# Build the project
$ cargo build --release

# The binary will be available at target/release/sysg

Contributing

Contributions to systemg are welcome! Please see the CONTRIBUTING.md file for guidelines.