doc(main): configuration variables and overall usage

README.md

@@ -1,9 +1,7 @@
-# forge
+# Universal Blue - Forge
 
-On-premises Universal Blue
-
-This repo is intended to provide the service units necessary to set up a
-self-hosted OS forge for custom images.
+On-premises Universal Blue. This repository is intended to provide the service units
+necessary to set up a self-hosted OS forge for custom images.
 
 > **Warning**
 > This project is "work in progress" and not ready for production
@@ -55,12 +53,42 @@ The shiny GUI is missing but this should not shy us away. See [usage](#usage) fo
 
 You can use the `forge.sh` to **setup**, **heat-up** and **cool-down** the forge.
 
+<!-- markdownlint-disable MD013 -->
+
 | Command                | Description                                                 |
 | ---------------------- | ----------------------------------------------------------- |
 | `./forge.sh setup`     | Setup the forge for the first time or update existing setup |
 | `./forge.sh heat-up`   | Start the forge                                             |
 | `./forge.sh cool-down` | Stop the forge                                              |
 
+<!-- markdownlint-enable MD013 -->
+
 ### Usage
 
-..tbd...
+Once the forge has been setup the following recipes are available via [just command runner](https://github.com/casey/just).
+
+<!-- markdownlint-disable MD013 -->
+
+| Just recipe           | Input argument          | Default argument value                      | Description                                  |
+| --------------------- | ----------------------- | ------------------------------------------- | -------------------------------------------- |
+| `forge_project-clone` | `forge_config_var_file` | $HOME/ublue-os_forge/forge_default_vars.env | Clone git project repository                 |
+| `forge_project-build` | `forge_config_var_file` | $HOME/ublue-os_forge/forge_default_vars.env | Build container image and upload to registry |
+
+<!-- markdownlint-enable MD013 -->
+
+All available settings for the `forge_config_var_file` are documented in the [variables.md](./docs/variables.md)
+file. To launch a recipe you simple run:
+
+```sh
+just -f forge.just {{ recipe_name }} {{ forge_config_var_file }}
+```
+
+**_Example:_**
+
+```sh
+just -f forge.just forge_project-clone /var/home/stephan/ublue-os_forge/my-forge-project.env
+```
+
+In case you don't have [just command runner](https://github.com/casey/just) available.
+Have a look at the [forge.just](./forge.just) file. It easy enough to understand which commands
+are executed via the just recipes.

docs/variables.md

@@ -0,0 +1,52 @@
+# Variables
+
+The following sections contains all important variables defined for daily usage.
+All variables mentioned here can be declared in a line-delimited file of environment variables.
+
+An example file on the host system with all variables available will be created on setup
+for you. By default it can be found under `$HOME/ublue-os_forge/forge_default_vars.env`.
+
+On playbook launch the variable file will be imported into the ansible container so that
+the settings are available during playbook execution.
+
+## group_vars/all/data.yml
+
+In the [data.yml](../ansible/group_vars/all/data.yml) all variables are defined
+which are used in the context of the data handling.
+
+<!-- markdownlint-disable MD013 -->
+
+| name                                     | type | environment variable | default value                               | description                                   |
+| ---------------------------------------- | ---- | -------------------- | ------------------------------------------- | --------------------------------------------- |
+| `forge_data_path`                        | str  | `FORGE_DATA_PATH`    | $HOME/ublue-os_forge                        | Path where forge will store files per default |
+| `forge_data_default_variables_file_path` | str  |                      | $HOME/ublue-os_forge/forge_default_vars.env | Path to default configuration file            |
+
+<!-- markdownlint-enable MD013 -->
+
+## group_vars/all/git.yml
+
+In the [git.yml](../ansible/group_vars/all/git.yml/) all variables are defined which are
+used in the context of the git repositories.
+
+<!-- markdownlint-disable MD013 -->
+
+| name                               | type | environment variable               | default value                             | description                                    |
+| ---------------------------------- | ---- | ---------------------------------- | ----------------------------------------- | ---------------------------------------------- |
+| `forge_git_repository_url`         | str  | `FORGE_GIT_REPOSITORY_URL`         | <https://github.com/ublue-os/bluefin.git> | Git repository url                             |
+| `forge_git_repository_destination` | str  | `FORGE_GIT_REPOSITORY_DESTINATION` | $HOME/ublue-os/forge/bluefin              | Git destination where repository is cloned to  |
+| `forge_git_repository_version`     | str  | `FORGE_GIT_REPOSITORY_VERSION`     | main                                      | Git repository branch or tag or commit version |
+
+<!-- markdownlint-enable MD013 -->
+
+## group_vars/all/registry.yml
+
+In the [registry.yml](../ansible/group_vars/all/registry.yml) all variables are defined
+which are used in the context of the container registry.
+
+<!-- markdownlint-disable MD013 -->
+
+| name                 | type | environment variable | default value        | description            |
+| -------------------- | ---- | -------------------- | -------------------- | ---------------------- |
+| `forge_registry_url` | str  | `FORGE_REGISTRY_URL` | registry.ublue.local | Container registry url |
+
+<!-- markdownlint-enable MD013 -->