Skip to content

armgit / floci

Public Imported from GitHub
0

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.md
index 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.
## Persistence
diff --git a/docs/configuration/initialization-hooks.md b/docs/configuration/initialization-hooks.md
index 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.
+
```yaml
floci:
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 file
diff --git a/mkdocs.yml b/mkdocs.yml
index 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