Light, fluffy, and always free - The AWS Local Emulator alternative
docs: improve initialization hooks documentation (#144)
Cyril Schumacher1e2950a3aa58
diff --git a/docs/configuration/docker-compose.md b/docs/configuration/docker-compose.mdindex 4809f0254a..15f160885c 100644--- a/docs/configuration/docker-compose.md+++ b/docs/configuration/docker-compose.md@@ -55,7 +55,7 @@ services:- ./init/stop.d:/etc/floci/init/stop.d:ro```-See [`initialization-hooks.md`](./initialization-hooks.md) for execution behavior and configuration details.+See [Initialization Hooks](./initialization-hooks.md) for execution behavior and configuration details.## Persistencediff --git a/docs/configuration/initialization-hooks.md b/docs/configuration/initialization-hooks.mdindex a8bc3fa853..920fd9ed44 100644--- a/docs/configuration/initialization-hooks.md+++ b/docs/configuration/initialization-hooks.md@@ -1,47 +1,110 @@# Initialization Hooks-Floci can execute shell scripts during startup and shutdown.+Floci allows you to execute custom shell scripts when it starts and stops. These scripts can help set up your+environment (creating buckets, populating data, configuring resources, etc.) or tidy up during shutdown.-## Directories+Hook scripts ending with `.sh` are discovered in the following directories:-- Startup hooks are loaded from `/etc/floci/init/start.d`-- Shutdown hooks are loaded from `/etc/floci/init/stop.d`+- **Startup hooks** (`/etc/floci/init/start.d`) run after Floci services are initialized, but before the environment is marked as ready.+- **Shutdown hooks** (`/etc/floci/init/stop.d`) run when Floci is shutting down, after `destroy()` is triggered.-Only files ending with `.sh` are executed.+If a hook directory does not exist or contains no `.sh` scripts, Floci skips it and continues normally.+If the hook path exists but is not a directory, it is ignored.-## Execution Model+## Execution-- Scripts are executed in lexicographical order-- Hook scripts are executed sequentially-- Hook execution is fail-fast: execution stops at the first script that fails or times out+### Execution Environment++Hooks run:++- Inside the Floci runtime environment (same context as Floci services)+- Using the configured shell (default: `/bin/bash`)+- With access to configured services and their endpoints+- With the same environment variables as Floci++Hooks can call Floci service endpoints directly from inside the container. If a hook depends on additional CLI tools,+make sure those tools are available in the runtime image.++### Execution Behavior++Scripts are executed:++- In **lexicographical (alphabetical) order**+- **Sequentially** (one at a time)++When execution order matters, prefix filenames with numbers such as `01-`, `02-`, and `03-`.++Execution uses a fail-fast strategy:++- If a script exits with a non-zero status, remaining hooks are not executed.+- If a script exceeds the configured timeout, it is terminated and remaining hooks are not executed.+- A hook failure marks the corresponding startup or shutdown phase as **failed**.++## Examples++The following examples assume the runtime image includes the AWS CLI and that Floci is reachable at+`http://localhost:4566`.++### Startup Hook++For example, a startup hook could look like this:++```sh+#!/bin/sh+set -eu++aws --endpoint-url http://localhost:4566 \+ ssm put-parameter \+ --name /demo/app/bootstrapped \+ --type String \+ --value true \+ --overwrite+```++This example assumes the script is stored at `/etc/floci/init/start.d/01-seed-parameter.sh`.+It seeds a known SSM parameter during startup so tests or local services can rely on it.++### Shutdown Hook++For example, a shutdown hook could look like this:++```sh+#!/bin/sh+set -eu++aws --endpoint-url http://localhost:4566 \+ ssm delete-parameter \+ --name /demo/app/bootstrapped+```++This example assumes the script is stored at `/etc/floci/init/stop.d/01-cleanup-parameter.sh`.+It removes the parameter during shutdown to leave the environment clean.## Configuration-| Key | Default | Description |-|---|---|---|-| `floci.init-hooks.shell-executable` | `/bin/bash` | Shell executable used to run hook scripts |-| `floci.init-hooks.timeout-seconds` | `30` | Maximum execution time per hook script before it is considered failed |-| `floci.init-hooks.shutdown-grace-period-seconds` | `2` | Time to wait after `destroy()` before forcing process termination |+You can customize hook behavior via configuration:++| Key | Default | Description |+|--------------------------------------------------|-------------|------------------------------------------------------------------------------------------------------------------|+| `floci.init-hooks.shell-executable` | `/bin/bash` | Shell executable used to run scripts |+| `floci.init-hooks.timeout-seconds` | `30` | Maximum execution time per script before it is terminated and considered failed |+| `floci.init-hooks.shutdown-grace-period-seconds` | `2` | Time to wait after calling `destroy()` before forcefully stopping the process (allows cleanup hooks to complete) |### Example+The following configuration can be useful when startup hooks perform more in-depth setup work, such as seeding test+data or provisioning resources before an integration test suite starts.+```yamlfloci:init-hooks:- shell-executable: /bin/bash- timeout-seconds: 30- shutdown-grace-period-seconds: 2+ shell-executable: /bin/sh+ timeout-seconds: 60+ shutdown-grace-period-seconds: 10```-## Docker Compose Example+In this example:-```yaml-services:- floci:- image: hectorvent/floci:latest- ports:- - "4566:4566"- volumes:- - ./init/start.d:/etc/floci/init/start.d:ro- - ./init/stop.d:/etc/floci/init/stop.d:ro-```+- `shell-executable` uses `/bin/sh` for portable POSIX-compatible scripts.+- `timeout-seconds: 60` gives startup hooks more time to complete initialization tasks.+- `shutdown-grace-period-seconds: 10` gives shutdown hooks more time to finish cleanup before Floci stops.\ No newline at end of filediff --git a/mkdocs.yml b/mkdocs.ymlindex e4b6a9b08f..f9adc5e2a1 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -64,6 +64,7 @@ nav:- Ports Reference: configuration/ports.md- application.yml Reference: configuration/application-yml.md- Storage Modes: configuration/storage.md+ - Initialization Hooks: configuration/initialization-hooks.md- Services:- Overview: services/index.md- SSM Parameter Store: services/ssm.md