Sablier

Free and open-source software that starts workloads on demand and stops them after a period of inactivity.

It integrates with reverse proxy plugins (Traefik, Caddy, Nginx, Envoy, etc.) to intercept incoming requests, wake up sleeping workloads, and display a waiting page until they're ready.

Whether you don't want to overload your Raspberry Pi, or your QA environment is used only once a week and wastes resources by keeping workloads running, Sablier might be the solution you need.

• Installation
  • Use the Docker image
  • Use the binary distribution
  • Compile your binary from the sources
  • Use the Helm Chart
• Quick Start
• Configuration
  • Configuration File
  • Environment Variables
  • Arguments
• Providers
  • Docker
  • Docker Swarm
  • Podman
  • Kubernetes
• Usage with Reverse Proxies
  • Apache APISIX
  • Caddy
  • Envoy
  • Istio
  • Nginx
  • Traefik
• Community
• Support
• Sponsor
  • DigitalOcean

Installation

You can install Sablier using one of the following methods:

• Use the Docker image
• Use the binary distribution
• Compile your binary from the sources
• Use the Helm Chart

Use the Docker image

<img src="./docs/assets/img/docker.svg" alt="Helm" width="100" align="right" /> <!-- x-release-please-start-version -->

<!-- x-release-please-end -->

• Docker Hub: sablierapp/sablier
• GitHub Container Registry: ghcr.io/sablierapp/sablier

Choose one of the Docker images and run it with a sample configuration file:

• sablier.yaml

<!-- x-release-please-start-version -->

docker run -p 10000:10000 -v /var/run/docker.sock:/var/run/docker.sock sablierapp/sablier:1.11.2

[!TIP] Verify the image signature to ensure authenticity:

gh attestation verify --owner sablierapp oci://sablierapp/sablier:1.11.2

<!-- x-release-please-end -->

Use the binary distribution

<img src="./docs/assets/img/github.svg" alt="Helm" width="100" align="right" />

Grab the latest binary from the releases page and run it:

./sablier --help

[!TIP] Verify the binary signature to ensure authenticity:

gh attestation verify sablier-1.10.3-linux-amd64.tar.gz -R sablierapp/sablier

Compile your binary from the sources

git clone git@github.com:sablierapp/sablier.git
cd sablier
make
# Output will change depending on your distro
./sablier_draft_linux-amd64

Use the Helm Chart

<img src="./docs/assets/img/helm.png" alt="Helm" width="100" align="right" />

Deploy Sablier to your Kubernetes cluster using the official Helm chart for production-ready deployments.

Add the Sablier Helm repository:

helm repo add sablierapp https://sablierapp.github.io/helm-charts
helm repo update

Install Sablier:

helm install sablier sablierapp/sablier

📚 Full Documentation | 💻 Chart Repository

---

Quick Start

[!NOTE] This quick start demonstrates Sablier with the Docker provider.

For other providers, see the Providers section.

<!-- omit in toc -->

1. Start your container to scale to zero

Run your container with Sablier labels:

docker run -d --health-cmd "/mimic healthcheck" -p 8080:80 --name mimic \
  --label sablier.enable=true \
  --label sablier.group=demo \
  sablierapp/mimic:v0.3.2 \
  -running -running-after=5s \
  -healthy=true -healthy-after=5s

Here we run sablierapp/mimic, a configurable web-server for testing purposes.

[!CAUTION] You should always use a healthcheck with your application that needs to be scaled to zero.

Without a healtheck, Sablier cannot distinguish a started container from a container ready to receive incoming requests.

<!-- omit in toc -->

2. Stop the Container

Stop the container to simulate a scaled-down state:

docker stop mimic

[!TIP] Sablier can automatically stop containers at startup using the --provider.auto-stop-on-startup flag, which will stop all containers with sablier.enable=true labels.

<!-- omit in toc -->

3. Start Sablier

Start the Sablier server with the Docker provider:

docker run --name sablier \
  -p 10000:10000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  sablierapp/sablier:1.10.5 \
  start --provider.name=docker

<!-- omit in toc -->

4. Request a Session

Call the Sablier API to start a session for the demo group:

curl -v http://localhost:10000/api/strategies/blocking\?group\=demo\&session_duration\=20s
* Request completely sent off
< HTTP/1.1 200 OK
< X-Sablier-Session-Status: ready

Sablier will start the mimic container automatically for 20 seconds..

[!TIP] Check out the Usage with Reverse Proxies section to integrate Sablier with Traefik, Caddy, Nginx, and more.

<!-- omit in toc -->

5. Verify the Container is Running

docker ps | grep mimic

<!-- omit in toc -->

6. Wait for Session Expiration

After the session duration (20 seconds in this example), Sablier will automatically stop the container.

# Wait 20 seconds, then check
docker ps -a | grep mimic

The container should be stopped.

---

Configuration

There are three ways to configure Sablier:

1. In a configuration file
2. As environment variables
3. As command-line arguments

Configuration sources are evaluated in the order listed above with later methods overriding earlier ones.

If no value is provided for a given option, a default value is used.

Configuration File

At startup, Sablier searches for a configuration file named sablier.yml (or sablier.yaml) in:

• /etc/sablier/
• $XDG_CONFIG_HOME/
• $HOME/.config/
• . (the working directory)

You can override this using the configFile argument.

sablier --configFile=path/to/myconfigfile.yml

provider:
  # Provider to use to manage containers (docker, swarm, kubernetes)
  name: docker 
server:
  # The server port to use
  port: 10000 
  # The base path for the API
  base-path: /
storage:
  # File path to save the state (default stateless)
  file:
sessions:
  # The default session duration (default 5m)
  default-duration: 5m
  # The expiration checking interval. 
  # Higher duration gives less stress on CPU. 
  # If you only use sessions of 1h, setting this to 5m is a good trade-off.
  expiration-interval: 20s
logging:
  level: debug
strategy:
  dynamic:
    # Custom themes folder, will load all .html files recursively (default empty)
    custom-themes-path:
    # Show instances details by default in waiting UI
    show-details-by-default: false
    # Default theme used for dynamic strategy (default "hacker-terminal")
    default-theme: hacker-terminal
    # Default refresh frequency in the HTML page for dynamic strategy
    default-refresh-frequency: 5s
  blocking:
    # Default timeout used for blocking strategy (default 1m)
    default-timeout: 1m

Environment Variables

Environment variables follow the same structure as the configuration file and are prefixed with SABLIER_. For example:

strategy:
  dynamic:
    custom-themes-path: /my/path

becomes

SABLIER_STRATEGY_DYNAMIC_CUSTOM_THEMES_PATH=/my/path

Arguments

To list all available arguments:

<!-- x-release-please-version-start -->

sablier --help

# or

docker run sablierapp/sablier:1.10.4 --help

<!-- x-release-please-end -->

Command-line arguments follow the same structure as the configuration file. For example:

strategy:
  dynamic:
    custom-themes-path: /my/path

becomes

sablier start --strategy.dynamic.custom-themes-path /my/path

<!-- ## Reference TODO: Add link to full auto-generated reference -->

Providers

Docker

<img src="./docs/assets/img/docker.svg" alt="Docker" width="100" align="right" />

Sablier integrates seamlessly with Docker Engine to manage container lifecycle based on demand.

Features:

• Connects to the Docker socket
• Starts/Stops containers
• Compatible with Docker Compose

📚 Full Documentation

---

Docker Swarm

<img src="./docs