From a6614de3ad4e3d0119a43e1c0b85145a58f4a187 Mon Sep 17 00:00:00 2001 From: Alexis Couvreur Date: Wed, 12 Nov 2025 00:38:24 -0500 Subject: [PATCH] docs: improve documentation clarity --- docs/README.md | 17 +++++++-------- docs/configuration.md | 26 +++++++++++++---------- docs/getting-started.md | 43 +++++++++++++++++++------------------- docs/health.md | 10 ++++----- docs/installation.md | 20 ++++++++---------- docs/plugins/overview.md | 14 ++++++------- docs/providers/overview.md | 8 +++---- docs/strategies.md | 8 +++---- docs/themes.md | 34 +++++++++++++++--------------- 9 files changed, 90 insertions(+), 90 deletions(-) diff --git a/docs/README.md b/docs/README.md index e72ad72..fee4ed0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/configuration.md b/docs/configuration.md index 6663a66..037a0d9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 ``` -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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 1173fec..0e2bf1f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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`. @@ -58,12 +58,11 @@ services: -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` -?> 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. diff --git a/docs/health.md b/docs/health.md index 5c89496..3384458 100644 --- a/docs/health.md +++ b/docs/health.md @@ -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`. ```yml diff --git a/docs/installation.md b/docs/installation.md index 54203ef..6a0f95c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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 \ ``` -## 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 ``` diff --git a/docs/plugins/overview.md b/docs/plugins/overview.md index f3aee5d..5b80c52 100644 --- a/docs/plugins/overview.md +++ b/docs/plugins/overview.md @@ -1,12 +1,12 @@ # Reverse Proxy Plugins -## What is a Reverse Proxy Plugin ? +## 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). \ No newline at end of file +Others require you to rebuild your reverse proxy with the plugin included (e.g., Caddy). \ No newline at end of file diff --git a/docs/providers/overview.md b/docs/providers/overview.md index 6e54f23..c5d7069 100644 --- a/docs/providers/overview.md +++ b/docs/providers/overview.md @@ -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) \ No newline at end of file +[See the active issues about providers](https://github.com/sablierapp/sablier/issues?q=is%3Aopen+is%3Aissue+label%3Aprovider) \ No newline at end of file diff --git a/docs/strategies.md b/docs/strategies.md index 7f6b134..84063aa 100644 --- a/docs/strategies.md +++ b/docs/strategies.md @@ -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 diff --git a/docs/themes.md b/docs/themes.md index 556ea4b..50e36df 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -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: ``` -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 `` tag -The auto refresh is done using the [HTML http-equiv Attribute](https://www.w3schools.com/tags/att_meta_http_equiv.asp). +The auto-refresh is accomplished using the [HTML 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 http-equiv Attribute` as follows: +The first step to creating your own theme is to include the `HTML http-equiv Attribute` as follows: ```html @@ -73,13 +73,13 @@ So the first step to create your own theme is to include the `HTML http-e ``` -## 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'