pebble

README

The Pebble service manager

Take control of your internal daemons!

Pebble is a lightweight Linux service manager that helps you orchestrate a set of local processes as an organised set. It resembles well-known tools such as supervisord, runit, or s6, in that it can easily manage non-system processes independently from the system services. However, it was designed with unique features such as layered configuration and an HTTP API that help with more specific use cases.

Pebble's key features:

• Layer-based configuration
• Service dependencies
• Service logs and log forwarding
• Health checks
• Notices (aggregated events)
• Identities
• Can be used in virtual machines and containers
• CLI commands
• HTTP API with a Go client and a Python client

Quick start

At any Linux shell:

go install github.com/canonical/pebble/cmd/pebble@latest
mkdir -p ~/.config/pebble/layers
export PEBBLE=$HOME/.config/pebble

echo """\
services:
    demo-service:
        override: replace
        command: sleep 1000
        startup: enabled
""" > $PEBBLE/layers/001-demo-service.yaml

pebble run

Read more about Pebble's general model here.

For a hands-on introduction to Pebble, we recommend going through the tutorial.

Getting help

To get the most out of Pebble, we recommend starting with the documentation.

You can create an issue and we will help!

Hacking and development

See HACKING.md for information on how to run and hack on the Pebble codebase during development. In short, use go run ./cmd/pebble.

Contributing

We welcome quality external contributions. We have good unit tests for much of the code, and a thorough code review process. Please note that unless it's a trivial fix, it's generally worth opening an issue to discuss before submitting a pull request.

Before you contribute a pull request you should sign the Canonical contributor agreement -- it's the easiest way for you to give us permission to use your contributions.