smanager 0.5.0

A simple server manager for self-hosted services

SManager

A simple server manager for self-hosted services, with VPN integration and support for local/systemd, Docker, and PHP runtimes.

When building a self-hosted setup, it’s common to end up with dozens of local services, Docker containers, and maintenance scripts scattered across your system. Tasks as simple as restarting or stopping a service can quickly become frustrating when there’s no clear overview of what is running, how components relate to each other, or how everything is managed.

SManager provides a simple and unified CLI for managing local, Docker, and PHP services, with built-in support for VPN integration and interactive metadata management.

Reseting all your music-related services becomes as simple as:

smanager group restart music

Features

• Unified service management for local/systemd, Docker, and PHP runtimes.
• VPN integration (Tailscale provider support).
• Interactive metadata creation and editing.
• YAML-based global configuration.
• Rich service status reporting with optional JSON output.

Phylosophy

SManager is designed to work alongside your existing setup, not replace it. However here are some best practices to get the most out of SManager:

• Use one directory per service (service directory), put all the service-related files there (metadata, scripts, Dockerfiles, documentation, etc).
• Define one directory to store all the service directories (services root).
• Each time you create a new service, create a metadata file for it using smanager metadata init and place it in its service directory.

SManager does not enforce any specific structure for your services, but following these guidelines will help you maintain a clear and organized setup that SManager can effectively manage. If you don't want to follow this structure, just point services_root to your $HOME and SManager will work with whatever it finds there.

Installation

pip install smanager

After installation, you need to configure SManager by running:

smanager config init
smanager config edit

An editor will open with the global configuration file. Set the services_root to the directory where you want to store your service directories, and configure the VPN provider if you are using one.

CLI Usage

Use this command pattern:

smanager <group> <command> [options]

Discover available commands at any level:

smanager --help
smanager <group> --help
smanager <group> <command> --help

Status Commands

Status is now a subcommand under each resource group:

smanager service status <service_id>
smanager group status <group_name>
smanager dependency status <dependency_name>
smanager all status

Optional JSON output is available for each status command:

smanager service status <service_id> --json

Info Commands

Info is available under each resource group and shows service name plus WebUI URL:

smanager service info <service_id>
smanager group info <group_name>
smanager dependency info <dependency_name>
smanager all info

Use --details to include extra operational columns:

smanager service info <service_id> --details

Metadata Commands

The metadata group provides interactive workflows for service metadata files.

Create Metadata

smanager metadata init

Optional output override:

smanager metadata init --output /path/to/sd_info.json

Edit Existing Metadata

smanager metadata edit

Edit a specific file directly:

smanager metadata edit --file /path/to/sd_info.json

Validate Metadata

Validate a single metadata file:

smanager metadata validate --file /path/to/sd_info.json

Validate all metadata files from a directory recursively:

smanager metadata validate --root /path/to/services

Use JSON output for CI/automation:

smanager metadata validate --root /path/to/services --json

Behavior summary:

• Interactive prompts with inline defaults.
• Runtime-aware sections (Docker, Local, and PHP).
• Multi-select support for groups and depends_on.
• Validation before writing changes.

PHP Runtime Metadata

For runtime.type: php, define the php section with:

• start_command (required)
• stop_command (required)
• status_command (optional, if present takes precedence over healthcheck for status)
• healthcheck_url (optional, used by status checks)
• healthcheck_timeout (optional, defaults to 3)
• working_dir (optional)
• env (optional map of environment variables)

Notes

• metadata init creates a new file.
• metadata edit modifies an existing file.
• Use command-specific --help for the latest options and examples.