sablier/docs/getting-started.md

Getting started

This Getting Started will get you through what you need to understand how to use Sablier as a scale to zero middleware with a reverse proxy.

Identify your provider

The first thing you need to do is to identify your Provider.

?> A Provider is how Sablier can interact with your instances and scale them up and down to zero.

You can check the available providers here.

Identify your reverse proxy

Once you've identified your Provider, you'll want to identify your Reverse Proxy.

?> Because Sablier is designed as an API that can be used on its own, reverse proxy integrations acts as a client of that API.

You can check the available reverse proxy plugins here

Connect it all together

• Let's say we're using the Docker Provider.
• Let's say we're using the Caddy Reverse Proxy Plugin.

1. Initial setup with Caddy

Suppose this is your initial setup with Caddy. You have your reverse proxy with a Caddyfile that does a simple reverse proxy on /whoami.

docker-compose.yaml

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

  whoami:
    image: acouvreur/whoami:v1.10.2

Caddyfile

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

At this point you can run docker compose up and go to http://localhost:8080/whoami and you will see your service.

2. Install Sablier with the Docker Provider

Add the Sablier container in the docker-compose.yaml file.

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

  whoami:
    image: acouvreur/whoami:v1.10.2

  sablier:
    image: sablierapp/sablier:1.10.1 # x-release-please-version
    command:
        - start
        - --provider.name=docker
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'

3. Add the Sablier Caddy Plugin to Caddy

Because Caddy does not provide any runtime evaluation for the plugins, we need to build Caddy with this specific plugin.

I'll use the provided Dockerfile to build the custom Caddy image.

docker build https://github.com/sablierapp/sablier.git#v1.8.1:plugins/caddy 
  --build-arg=CADDY_VERSION=2.8.4
  -t caddy:2.8.4-with-sablier

Then change the image to from caddy:2.8.4 to caddy:2.8.4-with-sablier

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

  whoami:
    image: acouvreur/whoami:v1.10.2

  sablier:
    image: sablierapp/sablier:1.10.1 # x-release-please-version
    command:
        - start
        - --provider.name=docker
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'

4. Configure Caddy to use the Sablier Caddy Plugin on the whoami service

This is how you opt in your services and link them with the plugin.

docker-compose.yaml

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

  whoami:
    image: acouvreur/whoami:v1.10.2
    labels:
      - sablier.enable=true
      - sablier.group=demo
  
  sablier:
    image: sablierapp/sablier:1.10.1 # x-release-please-version
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'

Caddyfile

:80 {
	route /whoami {
      sablier http://sablier:10000 {
        group demo
        session_duration 1m 
        dynamic {
            display_name My Whoami Service
        }
      }

	  reverse_proxy whoami:80
	}
}

Here we've configured the following things when we're accessing the service on http://localhost:8080/whoami:

• The containers that have the label sablier.group=demo will be started on demand
• The period of innactivity after which the containers should be shut down is one minute
• It uses the dynamic configuration and configures the title with My Whoami Service

?> We've assigned the group demo to the service, and we use this to identify the workload i