### Running the Custom Theme Example

Source: https://github.com/sablierapp/sablier/blob/main/examples/custom-theme/README.md

Commands to set up, run, and tear down the custom theme example. Ensure Docker and curl are installed.

```bash
# Download artwork, then start Sablier (app container is stopped).
make up

# Open the URL below in a browser to see the custom theme:
#   http://localhost:10000/api/strategies/dynamic?group=myapp&session_duration=1m&theme=my-theme&show_details=true
make demo

# Tear down
make down

```

--------------------------------

### Makefile Commands for Example

Source: https://github.com/sablierapp/sablier/blob/main/examples/restart-policy/README.md

These commands are used to set up, run, and inspect the containers for the restart policy example. They include starting Sablier, issuing blocking requests, and managing container lifecycles.

```makefile
make up
make start
make logs
make ps
make down
```

--------------------------------

### Run Example with Make

Source: https://github.com/sablierapp/sablier/blob/main/examples/anti-affinity/README.md

Convenience commands to set up, run a demo of the anti-affinity behavior, and tear down the example services.

```bash
# Start everything
make up

# Activate background, request streaming, watch background yield, then restore
make demo

# Tear down
make down
```

--------------------------------

### Start the Sablier Stack

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/getting-started.md

Use this command to launch all necessary services for Sablier. Ensure Docker is installed and running.

```bash
docker compose up -d
```

--------------------------------

### Uptime Kuma Integration Example

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/webhooks.md

Configure webhook endpoints for Uptime Kuma to send 'started' and 'stopped' events. This example shows how to use query parameters for status and messages.

```yaml
webhooks:
  endpoints:
    - url: https://uptime.example.com/api/push/<monitor-id>?status=up&msg=started
      events:
        - started
    - url: https://uptime.example.com/api/push/<monitor-id>?status=down&msg=stopped
      events:
        - stopped
```

--------------------------------

### Running the Example with Make

Source: https://github.com/sablierapp/sablier/blob/main/examples/multiple-groups/README.md

Provides make commands to set up, trigger team-specific sessions, and tear down the Sablier environment for the multiple groups example.

```bash
# Start Sablier with all managed services stopped
make up

# Trigger a team-a session (frontend + shared-api start)
make demo-team-a

# Trigger a team-b session (backend + shared-api start)
make demo-team-b

# Tear down
make down
```

--------------------------------

### Example 'started' webhook payload

Source: https://github.com/sablierapp/sablier/blob/main/examples/webhooks/README.md

A sample JSON payload representing a 'started' event, including the event type, instance name, and timestamp.

```json
{
  "event": "started",
  "instance": {
    "name": "webhooks-whoami-1"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}
```

--------------------------------

### Running the Jaeger Example with Docker Compose

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/advanced/observability/tracing.md

Use these commands to set up a tracing environment with Sablier, a target service, and Jaeger using Docker Compose. Navigate to the example directory, bring up the services, send a request to generate traces, and then view the traces in the Jaeger UI.

```sh
cd examples/tracing/jaeger
make up
make request-blocking   # sends a request and generates traces
make traces             # opens Jaeger UI at http://localhost:16686
```

--------------------------------

### Targeting a Group from a Reverse Proxy (Caddy)

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/concepts/groups.md

Configure your reverse proxy to target a specific group. This example shows how to use Caddy to start the 'demo' group when a request hits the '/whoami' route.

```caddy
route /whoami {
    sablier http://sablier:10000 {
        group demo
        session_duration 1m
    }
    reverse_proxy whoami:80
}
```

--------------------------------

### sablier start

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/reference/cli.md

Start the Sablier server. All configuration options apply to this command.

```APIDOC
## sablier start

### Description
Start the Sablier server.

### Options
Every option in the sections below configures this command.
```

--------------------------------

### Configure `ready-on-start` Label

Source: https://github.com/sablierapp/sablier/blob/main/examples/ready-on-start/README.md

Apply this label to an instance to indicate that it should be considered ready immediately upon starting, without waiting for its health check.

```yaml
labels:
  - "sablier.enable=true"
  - "sablier.group=home"
  - "sablier.ready-on-start=true"   # don't wait for health
```

--------------------------------

### Select Podman Provider via CLI

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/providers/podman.md

Start Sablier with the Podman provider using the command line interface.

```bash
sablier start --provider.name=podman
```

--------------------------------

### Enable Ready on Start in Docker Compose

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/readiness/ready-on-start.md

Use the `sablier.ready-on-start=true` label in your `docker-compose.yml` file to instruct Sablier to consider the service ready immediately after it starts, without performing a health check. This is beneficial for services that operate in the background and do not require a health check to be functional.

```yaml
# compose.yml
services:
  frigate:
    image: frigate:latest
    labels:
      - "sablier.enable=true"
      - "sablier.group=home"
      - "sablier.ready-on-start=true"   # start frigate, don't wait for health

```

--------------------------------

### Start, Demo, and Tear Down Sablier

Source: https://github.com/sablierapp/sablier/blob/main/examples/scale-mode/README.md

Use these make commands to manage the Sablier environment. `make up` starts all services, `make demo` triggers an active session to observe resource changes, and `make down` stops and removes them.

```bash
# Start everything
make up
```

```bash
# Trigger an active session and watch the resource transition
make demo
```

```bash
# Tear down
make down
```

--------------------------------

### Install Traefik Helm Chart

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/guides/code-server-traefik-kubernetes.md

Install the Traefik Helm chart using the specified values.yaml file into the kube-system namespace.

```bash
helm install traefik traefik/traefik -f values.yaml --namespace kube-system
```

--------------------------------

### Manual Sablier Setup and Session Request

Source: https://github.com/sablierapp/sablier/blob/main/examples/scale-mode/README.md

Manually start Sablier services with Docker Compose, request a blocking session using `curl`, and inspect CPU limits. This is useful for detailed testing and debugging.

```bash
docker compose up -d
```

```bash
# Request a session (blocks until whoami is ready, then returns)
curl 'http://localhost:10000/api/strategies/blocking?group=whoami&timeout=30s'
```

--------------------------------

### Blocking, Cold Start Performance Metrics

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/reference/performance.md

This output details performance metrics for the blocking strategy during a cold start. It highlights the significant latency difference between the first request (including container startup) and subsequent warm cache requests.

```text
Latency    1.67s  (avg)    5.02s  (max)
  p50  822 µs  |  p90  5.02s  |  p99  5.02s
2xx: 3   (3 sequential requests)
```

--------------------------------

### Sablier YAML Configuration Example

Source: https://github.com/sablierapp/sablier/blob/main/README.md

This is a comprehensive example of a Sablier configuration file in YAML format, covering provider, server, storage, sessions, logging, strategy, webhooks, and tracing settings.

```yaml
provider:
  # Provider to use to manage containers (docker, swarm, kubernetes, podman, proxmox_lxc)
  name: docker
  # Reject requests for containers/services that don't have the Sablier enable label
  reject-unlabeled-requests: false
  # Verify that the Sablier enable label is present when an instance expires
  verify-enabled-on-expiration: false
  docker:
    # Strategy to use when stopping containers (stop or pause)
    strategy: stop
server:
  # The server port to use
  port: 10000
  # The base path for the API
  base-path: /
  metrics:
    # Enable Prometheus metrics endpoint
    enabled: true
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: info
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: true
    # 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
webhooks:
  endpoints:
    # Notify an uptime-monitoring service every time an instance starts or stops.
    # - url: https://uptime.example.com/api/push/xxxxxxxx
    #   headers:
    #     Authorization: "Bearer <token>"
    #   events:
    #     - started
    #     - stopped
tracing:
  # Set enabled: true to export OpenTelemetry traces.
  enabled: false
  # exporterType selects the trace backend: "otlphttp" (default) or "stdout".
  exporterType: otlphttp
  # endpoint is the OTLP collector base URL (scheme + host + optional port).
  # For Jaeger: http://jaeger:4318
  # For Grafana Tempo: http://tempo:4318
  endpoint: http://localhost:4318
  # serviceName is the logical name that appears in the tracing backend.
  serviceName: sablier
  # samplingRate controls the fraction of requests traced (0.0 – 1.0).
  samplingRate: 1.0

```

--------------------------------

### Configure Docker Swarm Provider via CLI

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/providers/docker_swarm.md

Start Sablier with the Docker Swarm provider using the command line interface.

```bash
sablier start --provider.name=docker_swarm # or swarm
```

--------------------------------

### Start Sablier Server with Docker Provider

Source: https://github.com/sablierapp/sablier/blob/main/README.md

Launch the Sablier server using Docker, exposing its API and mounting the Docker socket for container management.

```bash
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
```

--------------------------------

### Sequence Diagram for Dependency Resolution

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/startup-dependencies/depends-on.md

Visualize the startup sequence when a blocking request arrives, showing how Sablier starts dependencies and waits for their conditions before starting the main application.

```mermaid
sequenceDiagram
    participant Client
    participant Sablier
    participant db
    participant migration
    participant app
    Client->>Sablier: blocking request for group app
    Sablier->>db: start
    db-->>Sablier: service_healthy
    Sablier->>migration: start
    migration-->>Sablier: service_completed_successfully
    Sablier->>app: start
    app-->>Client: ready
```

--------------------------------

### Run Blocking Cold Start Benchmark

Source: https://github.com/sablierapp/sablier/blob/main/benchmarks/README.md

Measures the full round-trip time, including Docker container start time, for the blocking strategy. Each request triggers a cold start. Override the default sample count by setting the N variable.

```bash
make bench-blocking-cold          # 3 samples (default)
make bench-blocking-cold N=10     # override sample count
```

--------------------------------

### Install Sablier with Helm

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/installation.md

Install the Sablier Helm chart into your Kubernetes cluster. This command deploys Sablier with default configurations.

```bash
helm install sablier sablierapp/sablier
```

--------------------------------

### Start a Docker Container with Sablier Labels

Source: https://github.com/sablierapp/sablier/blob/main/README.md

Run a Docker container with Sablier labels enabled for group 'demo'. Ensure a healthcheck is configured for proper scaling to zero functionality.

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

--------------------------------

### Docker Compose `depends_on` Example

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/providers/docker.md

Define service dependencies and conditions for startup order. Use `sablier.enable=true` to have Sablier manage the lifecycle of a service within a group.

```yaml
services:
  app:
    image: myapp
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      migration:
        condition: service_completed_successfully
    labels:
      - sablier.enable=true
      - sablier.group=mystack

  db:
    image: postgres
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 1s
    labels:
      - sablier.enable=true
      - sablier.group=mystack

  migration:
    image: myapp
    command: ["migrate"]
    restart: "no"
    depends_on:
      db:
        condition: service_healthy
```

--------------------------------

### Configure Docker Provider via CLI

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/providers/docker.md

Use the --provider.name=docker flag when starting Sablier via the command line to select the Docker provider.

```bash
sablier start --provider.name=docker
```

--------------------------------

### Start Full Stack

Source: https://github.com/sablierapp/sablier/blob/main/examples/auto-stop-externally-started/README.md

Starts the entire stack including managed and unmanaged containers using Docker Compose. The `--provider.auto-stop-on-startup` flag will stop the managed container if it was not initiated by Sablier.

```bash
make up
```

--------------------------------

### Manual Steps for Anti-Affinity Demo

Source: https://github.com/sablierapp/sablier/blob/main/examples/anti-affinity/README.md

Manual steps to demonstrate anti-affinity using Docker Compose and cURL. This involves starting services, activating one, requesting another to trigger yielding, and observing restoration after the session expires.

```bash
docker compose up -d

# 1. Activate the background service (gives it a live session)
curl 'http://localhost:10000/api/strategies/blocking?group=background&timeout=30s'
docker compose ps            # background is running

# 2. Request the streaming service — background must yield
curl 'http://localhost:10000/api/strategies/blocking?group=streaming&timeout=30s'
sleep 3
docker compose ps -a         # background is now exited (forced idle)

# 3. Let the streaming session expire, then check again
sleep 40
docker compose ps            # background is running again (restored)
```

--------------------------------

### Dynamic, Not-Ready (Cold) Performance Metrics

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/reference/performance.md

This output shows performance metrics for the dynamic strategy when the target container is not ready (cold start). It measures requests per second, latency, and throughput for requests that immediately return a not-ready status.

```text
Reqs/sec      4662.66    (avg)    6969.98  (max)
Latency        2.15ms    (avg)   138.45ms  (max)
  p50   1.93ms  |  p75   2.42ms  |  p90   3.01ms
  p95   3.57ms  |  p99   5.88ms
2xx: 139,415   Throughput: 20.39 MB/s
```

--------------------------------

### Manual Session Triggering with Docker Compose

Source: https://github.com/sablierapp/sablier/blob/main/examples/multiple-groups/README.md

Demonstrates manual steps to start Sablier, stop services, and trigger group-specific sessions using curl requests.

```bash
docker compose up -d
docker compose stop frontend backend shared-api

# Request team-a — blocks until frontend and shared-api are ready
curl 'http://localhost:10000/api/strategies/blocking?group=team-a&timeout=30s'

# Request team-b — blocks until backend and shared-api are ready
curl 'http://localhost:10000/api/strategies/blocking?group=team-b&timeout=30s'
```

--------------------------------

### Start and manage the stack

Source: https://github.com/sablierapp/sablier/blob/main/examples/metrics/prometheus/README.md

Commands to bring up the docker compose stack, request a blocking operation to wake the demo group, and view Sablier metrics.

```sh
make up
make request-blocking
make metrics
```

--------------------------------

### Configure CPU Scaling with Podman

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/scaling-resources/scale-cpu.md

Podman uses the same label configuration as Docker for CPU scaling. This example sets idle CPU to 0.1 cores and active CPU to 2.0 cores.

```yaml
services:
  myapp:
    image: myapp:latest
    labels:
      - "sablier.enable=true"
      - "sablier.group=myapp"
      - "sablier.idle.replicas=1"
      - "sablier.idle.cpu=0.1"
      - "sablier.active.cpu=2.0"
```

--------------------------------

### Confirm Services are Stopped

Source: https://github.com/sablierapp/sablier/blob/main/examples/depends-on/README.md

Verify that the application, database, and migration services are in a 'Created' state and only the Sablier service is running. This confirms the initial setup before triggering.

```bash
make ps
```

--------------------------------

### Analyze Container Dependency Logs

Source: https://github.com/sablierapp/sablier/blob/main/examples/depends-on/README.md

Examine these log entries to understand the sequence of container startup and dependency resolution. They indicate when containers are waiting for dependencies, when dependencies are met, and when containers are starting.

```log
level=DEBUG msg="waiting for depends_on dependency" dependency=db        condition=service_healthy
level=DEBUG msg="waiting for depends_on dependency" dependency=migration condition=service_completed_successfully
level=DEBUG msg="starting container" name=db
level=DEBUG msg="starting container" name=migration
level=DEBUG msg="starting container" name=app
```

--------------------------------

### Start a Whoami Group with Blocking Strategy

Source: https://github.com/sablierapp/sablier/blob/main/examples/docker-socket-proxy/README.md

Initiates the 'whoami' container group using a blocking strategy and waits for it to become ready. This command is used to test Sablier's container management capabilities through the proxy.

```bash
make start
```

--------------------------------

### Useful PromQL queries for Sablier metrics

Source: https://github.com/sablierapp/sablier/blob/main/examples/metrics/prometheus/README.md

Provides examples of PromQL queries to monitor Sablier's group locking status, active instances, cold-start times, session requests, and instance stops.

```promql
sablier_group_locked
```

```promql
sablier_group_active_instances
```

```promql
histogram_quantile(0.95, rate(sablier_instance_ready_duration_seconds_bucket[5m]))
```

```promql
sablier_session_requests_total
```

```promql
rate(sablier_instance_stops_total[5m])
```

--------------------------------

### Configure Running Hours and Days for an Instance

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/lifecycle/running-hours.md

Use `sablier.running-hours` and `sablier.running-days` labels in your `compose.yml` to define the daily availability window for your service. The instance will be proactively started and held warm during this period.

```yaml
# compose.yml
services:
  myapp:
    image: myapp:latest
    restart: unless-stopped
    labels:
      - "sablier.enable=true"
      - "sablier.group=myapp"
      - "sablier.running-hours=09:00-18:00"
      - "sablier.running-days=Mon,Tue,Wed,Thu,Fri"
```

--------------------------------

### Build Custom Caddy Image with Sablier Plugin

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/getting-started.md

Builds a custom Caddy Docker image that includes the Sablier plugin. Ensure CADDY_VERSION matches your Caddy installation.

```bash
docker build https://github.com/sablierapp/sablier-caddy-plugin.git \
  --build-arg=CADDY_VERSION=2.8.4 \
  -t caddy:2.8.4-with-sablier
```

--------------------------------

### Observe Log Messages

Source: https://github.com/sablierapp/sablier/blob/main/examples/ready-on-start/README.md

Examine these log messages to confirm that the `nvr` instance is reported as ready immediately after dispatch, even while in a starting state, and that the `web` instance only becomes ready after its health check passes.

```text
level=DEBUG msg="request to start instance dispatched" instance=nvr status=starting
# nvr is immediately reported as ready despite status=starting
level=DEBUG msg="set expiration for instance" instance=nvr expiration=1m0s
# web still needs its health check
level=INFO msg="instance is ready" instance=web
```

--------------------------------

### Sablier Deployment Log Output

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/guides/code-server-traefik-kubernetes.md

Example log output from the Sablier deployment, indicating successful initialization of the Kubernetes provider, storage, and server listening on port 10000.

```log
time=2026-01-01T12:00:00Z level=INFO msg="using provider \"kubernetes\""
time=2026-01-01T12:00:00Z level=INFO msg="initialized storage to /etc/sablier/state.json"
time=2026-01-01T12:00:00Z level=INFO msg="server listening on :10000"
```

--------------------------------

### Docker Compose Stack Commands

Source: https://github.com/sablierapp/sablier/blob/main/examples/tracing/jaeger/README.md

Commands to manage the Docker Compose stack for the tracing example. Use 'make up' to start, 'make request-blocking' to trigger a request, and 'make traces' to open the Jaeger UI.

```sh
make up                # start the stack (waits for Jaeger to be healthy)
make request-blocking  # trigger a blocking request to wake the "demo" group
make traces            # open Jaeger UI (macOS) at http://localhost:16686
```

--------------------------------

### Build and Run Sablier from Source

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/installation.md

Clone the Sablier repository, build the binary using `make`, and then run the compiled executable. The output binary name may vary by platform.

```bash
git clone git@github.com:sablierapp/sablier.git
cd sablier
make
# Output will vary depending on your platform
./sablier_draft_linux-amd64
```

--------------------------------

### Initial docker-compose.yaml for Caddy and Whoami

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/getting-started.md

This is the initial docker-compose.yaml file before integrating Sablier, setting up a Caddy reverse proxy for a whoami service.

```yaml
services:
  proxy:
    image: caddy:2.8.4
    ports:
      - "8080:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro

  whoami:
    image: acouvreur/whoami:v1.10.2
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/sablierapp/sablier/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for various types of changes.

```bash
git commit -m "feat(provider): add Podman support"
```

```bash
git commit -m "fix(api): resolve race condition in session management"
```

```bash
git commit -m "docs: update installation guide with new Docker image"
```

```bash
git commit -m "test(kubernetes): add integration tests for StatefulSets"
```

--------------------------------

### Configure Sablier to Auto-Stop Externally Started Instances

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/lifecycle/auto-stop-externally-started.md

Use this configuration in your compose file to enable Sablier's auto-stop functionality for externally started instances. This ensures that any container labeled `sablier.enable=true` that starts without Sablier's direct initiation will be automatically stopped.

```yaml
# compose.yml
services:
  sablier:
    image: sablierapp/sablier:{{< version >}}
    command:
      - start
      - --provider.name=docker
      - --provider.auto-stop-on-startup=true
      - --provider.auto-stop-externally-started=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

  managed:
    image: acouvreur/whoami:v1.10.2
    labels:
      - "sablier.enable=true"
      - "sablier.group=managed"
```

--------------------------------

### Filter Webhook by Event Type (Started)

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/webhooks.md

Configure a webhook endpoint to only receive 'started' events. This can be used for analytics or triggering specific workflows.

```yaml
webhooks:
  endpoints:
    - url: https://analytics.example.com/hooks/instance-started
      events:
        - started
```

--------------------------------

### Configure Auto Stop Externally Started Instances

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/reference/cli.md

Control whether Sablier continuously stops instances with sablier.enable=true that were not started by Sablier. The default value is false.

```yaml
# sablier.yaml
provider:
  auto-stop-externally-started: false
```

```bash
# Environment variable
SABLIER_PROVIDER_AUTO_STOP_EXTERNALLY_STARTED=false
```

```bash
# Command-line flag
--provider.auto-stop-externally-started=false
```

--------------------------------

### Configure Auto-Warm Externally Started Instances

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/reference/cli.md

Control whether Sablier continuously creates default-duration sessions for externally started instances with sablier.enable=true. This setting prevents them from being stopped.

```yaml
provider:
  auto-warm-externally-started: false
```

```bash
SABLIER_PROVIDER_AUTO_WARM_EXTERNALLY_STARTED=false
```

```bash
--provider.auto-warm-externally-started=false
```

--------------------------------

### Display Help for Sablier CLI

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/configuration.md

View all available command-line arguments for the Sablier server.

```bash
sablier --help
```

```bash
docker run sablierapp/sablier:{{< version >}} --help
```

--------------------------------

### View Real-time Logs

Source: https://github.com/sablierapp/sablier/blob/main/examples/auto-stop-externally-started/README.md

Monitors Sablier's logs in real-time to observe the 'externally started instance detected, stopping' message when a managed container is started externally.

```bash
make logs
```

--------------------------------

### Compile Sablier from Source

Source: https://github.com/sablierapp/sablier/blob/main/README.md

Clone the Sablier repository, navigate into the directory, and run `make` to compile the binary. The output binary name may vary.

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

--------------------------------

### Start Managed Container Externally

Source: https://github.com/sablierapp/sablier/blob/main/examples/auto-stop-externally-started/README.md

Manually starts the 'managed' container after the stack is already running. This action triggers Sablier's `--provider.auto-stop-externally-started` flag to stop the container.

```bash
make start-managed
```

--------------------------------

### Run Sablier Binary

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/installation.md

Execute the downloaded Sablier binary. Use the `--help` flag to see available command-line options.

```bash
./sablier --help
```

--------------------------------

### Start and Control Matrix Animation

Source: https://github.com/sablierapp/sablier/blob/main/pkg/theme/embedded/matrix.html

Starts the Matrix falling characters animation. It sets up intervals for background redraws and for spawning new falling lines. Optionally accepts a list of elements to use for custom text in the lines.

```javascript
this.run = ($linesList) => {
  if (redrawIntervalHandler === undefined) {
    redrawIntervalHandler = window.setInterval(this.redraw, this.redrawInterval);
  }
  if (dropsIntervalHandler === undefined) {
    const fn = () => {
      const randomColumn = Math.floor(Math.random() * (this.columnsCapacity + 1));
      const minSpeed = 200, maxSpeed = 50, randomSpeed = Math.floor(Math.random() * (maxSpeed - minSpeed + 1)) + minSpeed;
      const list = [];
      let line = undefined, offset = undefined;
      if ($linesList !== undefined) {
        Array.prototype.forEach.call($linesList.querySelectorAll('li'), $li => {
          const text = $li.innerText.trim();
          if (text.length > 0) {
            list.push(text);
          }
        });
        if (list.length > 0 && Math.random() > 0.4) {
          line = list[Math.floor(Math.random() * list.length)];
          offset = Math.floor(Math.random() * line.length);
          if (offset <= 5) {
            offset *= 3;
          }
        }
      }
      drawLine(randomColumn, randomSpeed, line, offset);
      if (dropsIntervalHandler !== undefined) {
        window.clearInterval(dropsIntervalHandler);
        dropsIntervalHandler = undefined;
      }
      dropsIntervalHandler = window.setInterval(fn, ((minSpeed + maxSpeed) / 2 * this.rowsCapacity) / this.columnsCapacity / 0.5);
    };
    fn();
  }
};
```

--------------------------------

### Run All Sablier Benchmarks

Source: https://github.com/sablierapp/sablier/blob/main/benchmarks/README.md

Execute all four benchmark scenarios sequentially. The 'make up' command is automatically invoked.

```bash
cd benchmarks/

make bench          # run all four scenarios in sequence
# or individually:
make bench-blocking-warm
make bench-blocking-cold
make bench-dynamic-warm
make bench-dynamic-cold
```

--------------------------------

### Mimic Configuration with `sablier.ready-after`

Source: https://github.com/sablierapp/sablier/blob/main/examples/ready-after/README.md

This YAML configuration applies labels to the `slow-starter` service. The `sablier.ready-after=15s` label specifically instructs Sablier to wait an additional 15 seconds after the service reports as healthy before considering it fully ready.

```yaml
labels:
  - "sablier.enable=true"
  - "sablier.group=slow-starter"
  - "sablier.ready-after=15s"   # wait 15 s after healthy before unblocking
```

--------------------------------

### Tear Down Stack

Source: https://github.com/sablierapp/sablier/blob/main/examples/auto-stop-externally-started/README.md

Stops and removes all containers and associated resources created by the Docker Compose setup.

```bash
make down
```

--------------------------------

### Display Sablier Help Information

Source: https://github.com/sablierapp/sablier/blob/main/README.md

Use the `--help` argument with the Sablier executable or within a Docker container to view all available command-line arguments and their descriptions.

```bash
sablier --help
```

```bash
docker run sablierapp/sablier:1.15.0 --help
```

--------------------------------

### Custom Theme HTML Structure

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/how-to-guides/loading-strategies/customize-theme.md

Example of an HTML file for a custom theme that references local CSS, JavaScript, and image assets.

```html
<!-- my-theme.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="refresh" content="{{ .RefreshFrequency }}" />
  <link rel="stylesheet" href="css/style.css">
</head>
<body>
  <img src="imgs/logo.png" alt="Logo">
  <p>Starting {{ .DisplayName }}...</p>
  <script src="js/app.js"></script>
</body>
</html>
```

--------------------------------

### Enable Metrics in Sablier Configuration

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/concepts/resource-efficiency.md

Add this configuration to your Sablier setup to enable metrics collection. Metrics will be available at the `/metrics` endpoint.

```yaml
server:
  metrics:
    enabled: true
```

--------------------------------

### Initial Caddyfile Configuration

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/getting-started.md

The initial Caddyfile configuration that sets up a route for the /whoami path to the whoami service.

```Caddyfile
:80 {
	route /whoami {
		reverse_proxy whoami:80
	}
}
```

--------------------------------

### Configure Auto Stop on Startup

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/reference/cli.md

Determine if Sablier should stop all sablier.enable=true instances running at startup that were not started by Sablier. The default value is true.

```yaml
# sablier.yaml
provider:
  auto-stop-on-startup: true
```

```bash
# Environment variable
SABLIER_PROVIDER_AUTO_STOP_ON_STARTUP=true
```

```bash
# Command-line flag
--provider.auto-stop-on-startup=true
```

--------------------------------

### Run Sablier Locally

Source: https://github.com/sablierapp/sablier/blob/main/CONTRIBUTING.md

Builds and runs the Sablier application locally, or runs it directly using `go run`. Use the `--help` flag for command-line options.

```bash
# Build and run
make build
./sablier start --help

# Or run directly
go run cmd/sablier/sablier.go start --provider.name=docker
```

--------------------------------

### Configure webhook endpoints in compose.yml

Source: https://github.com/sablierapp/sablier/blob/main/examples/webhooks/README.md

Defines the webhook endpoints in the Sablier configuration within compose.yml. By default, all events ('started' and 'stopped') are sent.

```yaml
webhooks:
  endpoints:
    - url: http://webhook-receiver:8080/webhook
      # No "events" filter → receives both "started" and "stopped"
```

--------------------------------

### Dynamic Cold Benchmark Results

Source: https://github.com/sablierapp/sablier/blob/main/benchmarks/README.md

Statistics for the dynamic scenario with a cold container. Shows requests per second, latency, and throughput, reflecting initial container startup time.

```text
Statistics        Avg      Stdev        Max
  Reqs/sec      4662.66    1087.19    6969.98
  Latency        2.15ms     1.61ms   138.45ms
  Latency Distribution
     50%     1.93ms
     75%     2.42ms
     90%     3.01ms
     95%     3.57ms
     99%     5.88ms
  HTTP codes:
    1xx - 0, 2xx - 139415, 3xx - 0, 4xx - 0, 5xx - 0
  Throughput:    20.39MB/s
```

--------------------------------

### Example 'stopped' webhook payload

Source: https://github.com/sablierapp/sablier/blob/main/examples/webhooks/README.md

A sample JSON payload representing a 'stopped' event, sent after the managed session expires and the instance is stopped.

```json
{
  "event": "stopped",
  "instance": {
    "name": "webhooks-whoami-1"
  },
  "timestamp": "2025-01-15T10:31:00Z"
}
```

--------------------------------

### Opt-in a Service with `sablier.enable`

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/concepts/configuring-instances.md

To have Sablier manage a service, it must include the `sablier.enable=true` label. This example shows how to apply this label to a Docker service.

```yaml
services:
  whoami:
    image: acouvreur/whoami:v1.10.2
    labels:
      - "sablier.enable=true"
      - "sablier.group=demo"
```

--------------------------------

### Build the Sablier Binary

Source: https://github.com/sablierapp/sablier/blob/main/CONTRIBUTING.md

Compiles the project to create a binary executable. The output binary will be in the current directory.

```bash
make build
```

--------------------------------

### Install Sablier with Docker Provider

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/getting-started.md

Adds the Sablier container to docker-compose.yaml, configuring it to use the Docker provider and requiring access to the Docker socket.

```yaml
services:
  proxy:
    image: caddy:2.8.4
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro

  whoami:
    image: acouvreur/whoami:v1.10.2
    restart: unless-stopped

  sablier:
    image: sablierapp/sablier:{{< version >}}
    restart: always
    command:
        - start
        - --provider.name=docker
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'
```

--------------------------------

### Select Podman Provider via Environment Variable

Source: https://github.com/sablierapp/sablier/blob/main/docs/content/tutorials/providers/podman.md

Configure the Podman provider by setting the SABLIER_PROVIDER_NAME environment variable.

```bash
SABLIER_PROVIDER_NAME=podman
```

--------------------------------

### Request a Sablier Session

Source: https://github.com/sablierapp/sablier/blob/main/README.md

Call the Sablier API to initiate a session for a specific group with a defined duration. Sablier will automatically start the associated container.

```bash
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
```

--------------------------------

### Generate Documentation Files

Source: https://github.com/sablierapp/sablier/blob/main/CONTRIBUTING.md

Regenerates various documentation files from Go source code, including CLI docs, label documentation, metrics documentation, theme schema, and OpenAPI specification.

```bash
make generate
```

--------------------------------

### Run Sablier Tests with Go Directly

Source: https://github.com/sablierapp/sablier/blob/main/CONTRIBUTING.md

Executes all tests in the project using the Go toolchain directly. This is an alternative to using the `make test` command.

```bash
go test ./...
```