Sablier
Sablier is an API that start containers for a given duration.
It provides an integrations with multiple reverse proxies and different loading strategies.
Which allows you to start your containers on demand and shut them down automatically as soon as there's no activity.
- Sablier
Quick start with Traefik
You will see how to use Sablier with Traefik in order to start your container automatically when reaching it by its route.
git clone https://github.com/acouvreur/sablier
cd sablier
docker-compose up -d
docker-compose stop whoami
# Now you go to http://localhost:8080/whoami/dynamic with your browser
# Or you can call the blocking URL, this will wait until whoami is started
curl http://localhost:8080/whoami/blocking
Hostname: 1d034329b651
IP: 127.0.0.1
IP: 172.18.0.2
RemoteAddr: 172.18.0.4:33052
GET /whoami/blocking HTTP/1.1
Host: localhost:8080
User-Agent: curl/7.68.0
Accept: */*
Accept-Encoding: gzip
X-Forwarded-For: 172.18.0.1
X-Forwarded-Host: localhost:8080
X-Forwarded-Port: 8080
X-Forwarded-Proto: http
X-Forwarded-Server: 1aea141808c5
X-Real-Ip: 172.18.0.1
Reverse proxies integration plugins
The reverse proxy integrations is probably what you're most interested about.
It leverage the API calls to Sablier to your reverse proxy middleware to wake up your instances on demand.
Traefik Middleware Plugin
- Traefik Middleware Plugin with Docker classic
- Traefik Middleware Plugin with Docker Swarm
- Traefik Middleware Plugin with Kubernetes
Guides
Sablier Guide: Code-Server + Traefik + Kubernetes Ingress
See Sablier Guide: Code-Server + Traefik + Kubernetes Ingress
Configuration
There are three different ways to define configuration options in Sablier:
- In a configuration file
- As environment variables
- In the command-line arguments
These ways are evaluated in the order listed above.
If no value was provided for a given option, a default value applies.
Configuration File
At startup, Sablier searches for configuration in a 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: trace
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
All environment variables can be used in the form of the config file such as
strategy:
dynamic:
custom-themes-path: /my/path
Becomes
STRATEGY_DYNAMIC_CUSTOM_THEMES_PATH=/my/path
Arguments
To get the list of all available arguments:
sablier --help
# or
docker run acouvreur/sablier[:version] --help
# ex: docker run acouvreur/sablier:v1.0.0 --help
All arguments can be used in the form of the config file such as
strategy:
dynamic:
custom-themes-path: /my/path
Becomes
sablier start --strategy.dynamic.custom-themes-path /my/path
Install Sablier on its own
You can install Sablier with the following flavors:
- Use the Docker image
- Use the binary distribution
- Compile your binary from the sources
Use the Docker image
- Docker Hub: acouvreur/sablier
- Github Container Registry: ghcr.io/acouvreur/sablier
Choose one of the Docker images and run it with one sample configuration file:
docker run -d -p 10000:10000 \
-v $PWD/sablier.yml:/etc/sablier/sablier.yml acouvreur/sablier:1.1.0
Use the binary distribution
Grab the latest binary from the releases page.
And run it:
./sablier --help
Compile your binary from the sources
git clone git@github.com:acouvreur/sablier.git
cd sablier
make
# Output will change depending on your distro
./sablier_draft_linux-amd64
Loading with a waiting page
The Dynamic Strategy provides a waiting UI with multiple themes. This is best suited when this interaction is made through a browser.
| Name | Preview |
|---|---|
ghost |
 |
shuffle |
 |
hacker-terminal |
 |
matrix |
 |
Dynamic Strategy Configuration
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
Creating your own loading theme
Blocking the loading until the session is ready
The Blocking Strategy waits for the instances to load before serving the request This is best suited when this interaction from an API.
strategy:
blocking:
# Default timeout used for blocking strategy (default 1m)
default-timeout: 1m
Saving the state to a file
You can save the state of the application in case of failure to resume your sessions.
For this you can use the storage configuration.
storage:
file: /path/to/file.json
If the file doesn't exist it will be created, and it will be syned upon exit.
Loaded instances that expired during the restart won't be changed though, they will simply be ignored.
Glossary
I'll use these terms in order to be provider agnostic.
- Session: A Session is a set of instances
- Instance: An instance is either a docker container, docker swarm service, kubernetes deployment or kubernetes statefulset
Versioning
Sablier follows the Semantic Versioning 2.0.0 Specification (SemVer).
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner
- PATCH version when you make backwards compatible bug fixes
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
This process is fully automated using Semantic Release.
The configuration is release.config.js.