mirrors/sablier
1
0
Fork 0
mirror of https://github.com/sablierapp/sablier.git synced 2025-12-21 13:23:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve documentation clarity

Browse Source
This commit is contained in:
Alexis Couvreur
2025-11-12 00:38:24 -05:00
parent 33209acc6c
commit a6614de3ad
9 changed files with 90 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/README.md
View File

@@ -1,24 +1,23 @@
# Sablier - Scale to Zero
Sablier is a **free** and **open-source** software that can scale your workloads on demand.
Sablier is a **free** and **open-source** software that scales your workloads on demand.
![Demo](assets/img/demo.gif)
Your workloads can be a docker container, a kubernetes deployment and more (see [providers](providers/overview) for the full list).
Your workloads can be a Docker container, a Kubernetes deployment, and more (see [providers](providers/overview) for the full list).
Sablier is an API that starts containers for a given duration.
Sablier is an API that start containers for a given duration.
It provides integrations with multiple reverse proxies and different loading strategies.
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.
This allows you to start your containers on demand and shut them down automatically when there's no activity.
## Glossary
I'll use these terms in order to be provider-agnostic.
Throughout this documentation, we use these terms to remain 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
- **Session**: A session is a set of **instances**
- **Instance**: An instance is either a Docker container, Docker Swarm service, Kubernetes deployment, or Kubernetes StatefulSet
## Credits

26
docs/configuration.md
View File

@@ -1,25 +1,25 @@
# Configuration
There are three different ways to define configuration options in Sablier:
There are three ways to define configuration options in Sablier:
1. In a configuration file
2. As environment variables
3. In the command-line arguments
3. As command-line arguments
These ways are evaluated in the order listed above.
These methods are evaluated in the order listed above, with later methods overriding earlier ones.
If no value was provided for a given option, a default value applies.
If no value is provided for a given option, a default value is used.
## Configuration File
At startup, Sablier searches for configuration in a file named sablier.yml (or sablier.yaml) in:
At startup, Sablier searches for a configuration file named `sablier.yml` (or `sablier.yaml`) in the following locations:
- `/etc/sablier/`
- `$XDG_CONFIG_HOME/`
- `$HOME/.config/`
- `.` *(the working directory).*
- `.` *(the working directory)*
You can override this using the configFile argument.
You can override this by using the `configFile` argument:
```bash
sablier --configFile=path/to/myconfigfile.yml
@@ -63,7 +63,9 @@ strategy:
## Environment Variables
All environment variables can be used in the form of the config file such as
All configuration options can be set as environment variables. The variable names follow the structure of the configuration file.
For example, this configuration:
```yaml
strategy:
@@ -71,7 +73,7 @@ strategy:
custom-themes-path: /my/path
```
Becomes
Becomes:
```bash
STRATEGY_DYNAMIC_CUSTOM_THEMES_PATH=/my/path
@@ -91,7 +93,9 @@ docker run sablierapp/sablier:1.10.1 --help
```
<!-- x-release-please-end -->
All arguments can be used in the form of the config file such as
All configuration options can be used as command-line arguments. The argument names follow the structure of the configuration file.
For example, this configuration:
```yaml
strategy:
@@ -99,7 +103,7 @@ strategy:
custom-themes-path: /my/path
```
Becomes
Becomes:
```bash
sablier start --strategy.dynamic.custom-themes-path /my/path

43
docs/getting-started.md
View File

@@ -1,33 +1,33 @@
# Getting started
# 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.
This guide will walk you through setting up Sablier as a scale-to-zero middleware with a reverse proxy.
![integration](/assets/img/integration.png)
## Identify your provider
## Identify Your Provider
The first thing you need to do is to identify your [Provider](providers/overview).
The first thing you need to do is identify your [Provider](providers/overview).
?> A Provider is how Sablier can interact with your instances and scale them up and down to zero.
?> A Provider is how Sablier interacts with your instances to scale them up and down to zero.
You can check the available providers [here](providers/overview?id=available-providers).
## Identify your reverse proxy
## Identify Your Reverse Proxy
Once you've identified your [Provider](providers/overview), you'll want to identify your [Reverse Proxy](plugins/overview).
Once you've identified your [Provider](providers/overview), you'll need to identify your [Reverse Proxy](plugins/overview).
?> Because Sablier is designed as an API that can be used on its own, reverse proxy integrations acts as a client of that API.
?> Because Sablier is designed as an API that can be used independently, reverse proxy integrations act as clients of that API.
You can check the available reverse proxy plugins [here](plugins/overview?id=available-reverse-proxies)
## Connect it all together
## Connect It All Together
- Let's say we're using the [Docker Provider](providers/docker).
- Let's say we're using the [Caddy Reverse Proxy Plugin](plugins/caddy).
### 1. Initial setup with Caddy
### 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`.
Suppose this is your initial setup with Caddy. You have your reverse proxy with a Caddyfile that performs a simple reverse proxy on `/whoami`.
<!-- tabs:start -->
@@ -58,12 +58,11 @@ services:
<!-- tabs:end -->
At this point you can run `docker compose up` and go to `http://localhost:8080/whoami` and you will see your service.
Now you can run `docker compose up` and navigate to `http://localhost:8080/whoami` to see your service.
### 2. Install Sablier with the Docker Provider
Add the Sablier container in the `docker-compose.yaml` file.
Add the Sablier container to the `docker-compose.yaml` file.
```yaml
services:
@@ -88,9 +87,9 @@ services:
### 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.
Because Caddy does not provide runtime plugin evaluation, we need to build Caddy with this specific plugin.
I'll use the provided Dockerfile to build the custom Caddy image.
We'll use the provided Dockerfile to build the custom Caddy image.
```bash
docker build https://github.com/sablierapp/sablier-caddy-plugin.git
@@ -98,7 +97,7 @@ docker build https://github.com/sablierapp/sablier-caddy-plugin.git
-t caddy:2.8.4-with-sablier
```
Then change the image to from `caddy:2.8.4` to `caddy:2.8.4-with-sablier`
Then change the image from `caddy:2.8.4` to `caddy:2.8.4-with-sablier`
```yaml
services:
@@ -168,11 +167,11 @@ services:
}
```
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`
Here we've configured the following for when accessing the service at `http://localhost:8080/whoami`:
- Containers with the label `sablier.group=demo` will be started on demand
- The period of inactivity after which containers should be shut down is one minute
- It uses the dynamic configuration and sets the display name to `My Whoami Service`
<!-- tabs:end -->
?> We've assigned the group `demo` to the service, and we use this to identify the workload.
?> We've assigned the group `demo` to the service, which is how we identify the workload.

10
docs/health.md
View File

@@ -1,17 +1,17 @@
## Sablier Healthcheck
### Using the `/health` route
### Using the `/health` Route
You can use the route `/health` to check for healthiness.
You can use the `/health` route to check for service health.
- Returns 200 `OK` when ready
- Returns 503 `Service Unavailable` when terminating
### Using the `sablier health` command
### Using the `sablier health` Command
You can use the command `sablier health` to check for healthiness.
You can use the `sablier health` command to check for service health.
`sablier health` takes on argument `--url` which defaults to `http://localhost:10000/health`.
The `sablier health` command takes one argument, `--url`, which defaults to `http://localhost:10000/health`.
<!-- x-release-please-start-version -->
```yml

20
docs/installation.md
View File

@@ -1,17 +1,17 @@
# Install Sablier on its own
# Install Sablier
You can install Sablier with the following flavors:
You can install Sablier using one of the following methods:
- Use the Docker image
- Use the binary distribution
- Compile your binary from the sources
- Compile from source
## Use the Docker image
## Use the Docker Image
- **Docker Hub**: [sablierapp/sablier](https://hub.docker.com/r/sablierapp/sablier)
- **GitHub Container Registry**: [ghcr.io/sablierapp/sablier](https://github.com/sablierapp/sablier/pkgs/container/sablier)
Choose one of the Docker images and run it with one sample configuration file:
Choose one of the Docker images and run it with a sample configuration file:
- [sablier.yaml](https://raw.githubusercontent.com/sablierapp/sablier/main/sablier.sample.yaml)
@@ -22,22 +22,20 @@ docker run -d -p 10000:10000 \
```
<!-- x-release-please-end -->
## Use the binary distribution
## Use the Binary Distribution
Grab the latest binary from the [releases](https://github.com/sablierapp/sablier/releases) page.
And run it:
Download the latest binary from the [releases](https://github.com/sablierapp/sablier/releases) page and run it:
```bash
./sablier --help
```
## Compile your binary from the sources
## Compile from Source
```bash
git clone git@github.com:sablierapp/sablier.git
cd sablier
make
# Output will change depending on your distro
# Output will vary depending on your platform
./sablier_draft_linux-amd64
```

12
docs/plugins/overview.md
View File

@@ -2,11 +2,11 @@
## What is a Reverse Proxy Plugin?
Reverse proxy plugins are the integration with a reverse proxy.
Reverse proxy plugins provide integration with a 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.
?> Because Sablier is designed as an API that can be used independently, reverse proxy integrations act as clients of that API.
It leverages the API calls to plugin integration to catch in-flight requests to Sablier.
They leverage API calls to intercept in-flight requests and communicate with Sablier.
![Reverse Proxy Integration](../assets/img/reverse-proxy-integration.png)
@@ -32,8 +32,8 @@ It leverages the API calls to plugin integration to catch in-flight requests to
*Your Reverse Proxy is not on the list? [Open an issue to request the missing reverse proxy integration here!](https://github.com/sablierapp/sablier/issues/new?assignees=&labels=enhancement%2C+reverse-proxy&projects=&template=reverse-proxy-integration-request.md&title=Add+%60%5BREVERSE+PROXY%5D%60+reverse+proxy+integration)*
## Runtime and Compiled plugins
## Runtime and Compiled Plugins
Some reverse proxies have the capability to evaluate the plugins at runtime (Traefik with Yaegi, NGINX with Lua and JS plugins) which means the reverse proxy provides a way to consume the plugin directly.
Some reverse proxies can evaluate plugins at runtime (e.g., Traefik with Yaegi, NGINX with Lua and JavaScript plugins), which means the reverse proxy can consume the plugin directly without recompilation.
Some others enforce you to rebuild your reverse proxy (Caddy).
Others require you to rebuild your reverse proxy with the plugin included (e.g., Caddy).

8
docs/providers/overview.md
View File

@@ -2,15 +2,15 @@
## What is a Provider?
A Provider is how Sablier can interact with your instances.
A Provider is how Sablier interacts with your instances.
A Provider typically have the following capabilities:
A Provider typically has the following capabilities:
- Start an instance
- Stop an instance
- Get the current status of an instance
- Listen for instance lifecycle events (started, stopped)
## Available providers
## Available Providers
| Provider | Name | Details |
|------------------------------|---------------------------|------------------------------------------------------------------|
@@ -21,4 +21,4 @@ A Provider typically have the following capabilities:
*Your Provider is not on the list? [Open an issue to request the missing provider here!](https://github.com/sablierapp/sablier/issues/new?assignees=&labels=enhancement%2C+provider&projects=&template=instance-provider-request.md&title=Add+%60%5BPROVIDER%5D%60+provider)*
[See the active issues about the providers](https://github.com/sablierapp/sablier/issues?q=is%3Aopen+is%3Aissue+label%3Aprovider)
[See the active issues about providers](https://github.com/sablierapp/sablier/issues?q=is%3Aopen+is%3Aissue+label%3Aprovider)

8
docs/strategies.md
View File

@@ -2,11 +2,11 @@
## Dynamic Strategy
The **Dynamic Strategy** provides a waiting page for your session.
The **Dynamic Strategy** displays a waiting page while your session starts.
![Demo](assets/img/demo.gif)
?> This strategy is well suited for a user that would access a frontend directly and expects to see a loading page.
?> This strategy is ideal for users accessing a frontend directly, as they'll see a loading page while their services start.
```plantuml
@startuml
@@ -37,9 +37,9 @@ User <-- Proxy: Content
```
## Blocking Strategy
The **Blocking Strategy** hangs the request until your session is ready.
The **Blocking Strategy** holds the request until your session is ready.
?> This strategy is well suited for an API communication.
?> This strategy is ideal for API communication, where clients expect to wait for a response.
```plantuml
@startuml

34
docs/themes.md
View File

@@ -1,10 +1,10 @@
# Themes
Sablier comes with a set of default theme that you can use.
Sablier comes with a set of default themes that you can use.
You can also extend the themes by providing your own and they will be templated as Go Templates.
You can also extend the themes by providing your own, which will be rendered as Go Templates.
## The embedded themes
## The Embedded Themes
| Name | Preview |
@@ -16,9 +16,9 @@ You can also extend the themes by providing your own and they will be templated
## Custom themes locations
## Custom Themes Locations
You can use the argument `--strategy.dynamic.custom-themes` to define the location to search upon starting.
You can use the `--strategy.dynamic.custom-themes` argument to define the location where Sablier should search for themes at startup.
By default, the docker image looks for themes located inside the `/etc/sablier/themes` folder.
@@ -33,12 +33,12 @@ services:
```
<!-- x-release-please-end -->
It will look recursively for themes with the `.html` extension.
Sablier will recursively search for themes with the `.html` extension.
- You **cannot** load new themes added in the folder without restarting
- You **can** modify the existing themes files
- You **cannot** load new themes added to the folder without restarting
- You **can** modify existing theme files without restarting
## Create a custom theme
## Create a Custom Theme
Themes are served using [Go Templates](https://pkg.go.dev/text/template).
@@ -59,11 +59,11 @@ Themes are served using [Go Templates](https://pkg.go.dev/text/template).
### The `<meta http-equiv="refresh" />` tag
The auto refresh is done using the [HTML <meta> http-equiv Attribute](https://www.w3schools.com/tags/att_meta_http_equiv.asp).
The auto-refresh is accomplished using the [HTML <meta> http-equiv Attribute](https://www.w3schools.com/tags/att_meta_http_equiv.asp).
> Defines a time interval for the document to refresh itself.
So the first step to create your own theme is to include the `HTML <meta> http-equiv Attribute` as follows:
The first step to creating your own theme is to include the `HTML <meta> http-equiv Attribute` as follows:
```html
<head>
@@ -73,13 +73,13 @@ So the first step to create your own theme is to include the `HTML <meta> http-e
</head>
```
## The `showDetails` option
## The `showDetails` Option
If `showDetails` is set to `false` then the `.InstanceStates` will be an empty array.
If `showDetails` is set to `false`, the `.InstanceStates` will be an empty array.
## How to load my custom theme
## How to Load Your Custom Theme
You can load themes by specifying their name and their relative path from the `--strategy.dynamic.custom-themes-path` value.
You can load themes by specifying their name and relative path from the `--strategy.dynamic.custom-themes-path` value.
```bash
/my/custom/themes/
@@ -89,13 +89,13 @@ You can load themes by specifying their name and their relative path from the `-
└── secret.html # special/secret
```
Such as
For example:
```bash
curl 'http://localhost:10000/api/strategies/dynamic?session_duration=1m&names=nginx&theme=custom1'
```
## See the available themes from the API
## See the Available Themes from the API
```bash
curl 'http://localhost:10000/api/strategies/dynamic/themes'