Pserv: Key Features and How It WorksPserv is a lightweight, modular service management tool designed to simplify running background services, daemons, and small web applications. It aims to provide a minimal, declarative interface for configuring, launching, supervising, and logging processes, targeting developers and small teams who want predictable, low-overhead service management without the complexity of full orchestration platforms.
What Pserv Does (Overview)
Pserv manages lifecycle and supervision of processes: start, stop, restart, monitor, and automatically recover failing services. It focuses on simplicity and predictability: configuration is typically file-based and declarative, and the runtime behavior is transparent.
Typical use cases:
- Running development microservices locally.
- Supervising small production daemons on single machines or VMs.
- Acting as a process supervisor for containerless deployments.
- Lightweight alternative to heavier init systems when you need only a few services.
Core Design Principles
- Minimal footprint: small memory and CPU overhead.
- Declarative configuration: services described in config files.
- Predictable restarts: clear, configurable restart policies.
- Transparent logging: structured logs with rotation.
- Extensibility: plugin hooks or simple scripting integration.
Main Components
-
Configuration files
- Usually YAML or TOML files that describe each service, command, environment variables, working directory, user, restart policy, and resource limits.
- Example fields: name, exec, args, env, cwd, user, restart, max_retries, stdout, stderr, autostart.
-
Supervisor daemon
- The core process that reads configs, launches services, monitors child processes, and handles signals (SIGTERM, SIGINT) for graceful shutdown.
-
Logging subsystem
- Captures stdout/stderr, optionally formats logs (JSON/plain), supports log rotation and retention policies, and can forward logs to external sinks.
-
Health checks and readiness probes
- Simple built-in checks (exit code monitoring, TCP/HTTP probes) to mark services healthy/unhealthy and trigger restarts or alerts.
-
CLI
- Commands for managing services: pserv start/stop/restart/status/list/logs/reload.
- Enables ad-hoc management and integration with scripts.
Key Features (Detailed)
Restart Policies
- Configurable restart policies such as never, on-failure, always, and on-watchdog. Policies usually include backoff settings (linear/exponential) and limits for maximum retries to avoid restart loops.
Process Supervision
- Supervises child processes directly (not via shell wrappers) to capture correct exit codes and signals.
- Supports process groups so signals can be propagated to entire trees (useful for multi-process apps).
Logging and Log Rotation
- Structured logging options (plain text or JSON).
- Built-in rotation based on size or time, and retention settings to limit disk usage.
- Optionally compress rotated logs.
Resource Controls
- Soft resource limits (ulimit-style) for CPU time, file descriptors, and memory.
- Option to integrate with cgroups on Linux for stronger resource isolation.
Health Checks and Liveness
- Built-in health probes: check an HTTP endpoint, TCP port, or run a custom command.
- Support for readiness and liveness checks to control whether a service is considered ready for traffic.
Graceful Shutdown and Signal Handling
- Graceful shutdown support that sends configurable signals (SIGTERM, SIGINT) with a configurable timeout before forcing SIGKILL.
- Hooks for pre-stop and post-start scripts to run custom actions.
Environment and Secrets
- Environment variable templating and support for secret files or integrations with simple secret stores (file-based or external providers via plugins).
- Ability to generate environment from a .env file with interpolation.
Service Dependencies and Ordering
- Declare dependencies between services so Pserv can ensure correct startup/shutdown order (e.g., database before app).
- Optional wait-for-ready semantics rather than just process start.
Metrics and Observability
- Exposes basic metrics (uptime, restarts, exit codes) via a metrics endpoint (Prometheus format) or local status commands.
- Integrations for forwarding metrics/logs to external monitoring systems.
Hooks and Extensibility
- Lifecycle hooks (pre-start, post-start, pre-stop) to run arbitrary scripts.
- Plugin API for adding custom behaviors like new health checks, log forwarders, or service discovery adapters.
Security Features
- Run services as unprivileged users.
- Namespace/chroot options on POSIX systems for extra isolation.
- Drop capabilities or configure seccomp profiles where supported.
Configuration Reloading
- Support for reloading configuration without full restart: add/remove services, change log settings, or adjust env vars with minimal disruption.
How Pserv Works — Typical Flow
-
Initialization
- Pserv reads one or more configuration files from default locations or a specified path.
- Validates the configuration and resolves templated variables.
-
Bootstrapping services
- For each service marked autostart, Pserv spawns the process with the specified environment, cwd, and UID/GID.
- Sets up log capture, health probes, and resource limits.
-
Monitoring and supervision
- The supervisor waits on child processes, monitors liveness, collects exit codes, and applies restart policies.
- On a failure, it evaluates backoff/retry rules and either restarts the service or marks it failed.
-
Health and readiness
- Health checks run periodically; a service failing health probes can be restarted or flagged for attention.
- Dependencies and readiness gates prevent dependent services from starting until prerequisites are ready.
-
Shutdown and reload
- On receiving a shutdown signal, Pserv runs pre-stop hooks, sends the configured termination signal to services, waits for graceful termination, then forces kill if necessary.
- On configuration reload, Pserv compares old vs new configs and applies changes incrementally.
Example configuration (YAML)
services: web: exec: /usr/local/bin/my-web args: ["--port", "8080"] env: DATABASE_URL: "postgres://db:5432/app" cwd: /var/www/myapp user: appuser autostart: true restart: on-failure max_retries: 5 stdout: /var/log/pserv/web.out.log stderr: /var/log/pserv/web.err.log health: http: path: /health port: 8080 interval: 10s timeout: 2s Comparison with Alternatives
| Feature | Pserv | systemd | supervisord |
|---|---|---|---|
| Lightweight | Yes | No (heavier) | Yes |
| Declarative config | Yes | Yes | Partial |
| Health probes | Built-in | Via services | Requires plugins |
| Log rotation | Built-in | journalctl | External |
| Cross-platform | Mostly POSIX | Linux-only | Python-based, cross-platform |
| Extensible hooks | Yes | Yes | Yes |
Best Practices
- Use explicit restart policies to avoid tight restart loops.
- Keep services unprivileged; run as dedicated users.
- Use health checks for dependent services instead of fixed delays.
- Centralize logs and set reasonable retention/rotation to avoid disk exhaustion.
- Test configuration reloads in staging before production.
Limitations and When Not to Use Pserv
- Not intended as a full cluster orchestrator — lacks scheduling, service discovery across nodes, and automatic scaling.
- Limited built-in secrets management compared to dedicated secret stores.
- On systems already standardized on systemd for service management, replacing it may be unnecessary or counterproductive.
Conclusion
Pserv is a practical, minimalist supervisor for developers and small ops teams who need predictable lifecycle management for processes without adopting heavyweight orchestration. It provides the essentials — declarative configs, robust restart policies, logging, health checks, and resource controls — while keeping the runtime small and understandable.
If you want, I can convert this into a blog post with images, add examples for Windows/macOS specifics, or produce a tutorial showing step-by-step setup and commands.
Leave a Reply