diff --git a/README.md b/README.md index 41104b5..97cce11 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ The reverse proxy dashboard is available at ### Container Registry As container registry we make use of the [Docker Registry 2.0](https://hub.docker.com/_/registry/) -implementation for storing and distributing container images +implementation for storing and distributing container images. The container registry API is available at @@ -47,11 +47,14 @@ The container registry API is available at The blacksmith's work is done with [Ansible](https://docs.ansible.com/ansible/latest/index.html). -The shiny GUI is missing but this should not shy us away. See [usage](#usage) for instructions. +There are two methods of operating the forge, either via a GUI available at +or via [just command runner](https://github.com/casey/just). + +Detailed usage instructions are available in the [documentation](./docs/index.md) section. ## Handling the forge -You can use the `forge.sh` to **setup**, **heat-up** and **cool-down** the forge. +You can use the `forge.sh` to **setup**, **heat-up** or **cool-down** the forge. @@ -62,33 +65,3 @@ You can use the `forge.sh` to **setup**, **heat-up** and **cool-down** the forge | `./forge.sh cool-down` | Stop the forge | - -### Usage - -Once the forge has been setup the following recipes are available via [just command runner](https://github.com/casey/just). - - - -| 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 | - - - -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 ~/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. diff --git a/docs/gui.md b/docs/gui.md new file mode 100644 index 0000000..15f5812 --- /dev/null +++ b/docs/gui.md @@ -0,0 +1 @@ +# Usage with GUI diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4ccdb78 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,67 @@ +# Universal Blue - Forge + +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. + +## Configuration + +Since we are using ansible in the background, all user configurations are loaded via +[`extra-vars`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html#defining-variables-at-runtime) +at runtime. No worries on how things are plugged together, you only have to know where +to create your configuration files. That's all. + +So, during forge setup a podman volume `ublue-os_forge-data` is created. All user configuration +etc. is stored there. You can inspect the volume with: + +```sh +❯ podman volume inspect ublue-os_forge-data +[ + { + "Name": "ublue-os_forge-data", + "Driver": "local", + "Mountpoint": "/var/home/stephan/.local/share/containers/storage/volumes/ublue-os_forge-data/_data", + "CreatedAt": "2024-05-06T21:25:28.818751853+02:00", + "Labels": {}, + "Scope": "local", + "Options": {}, + "MountCount": 0, + "NeedsCopyUp": true, + "LockNumber": 98 + } +] +``` + +Under the `"Mountpoint:"` you find the actual path on your file system. I would recommend you +symlink this folder to a path more rememberable. For example you can do: + +```sh +FORGE_POD_DATA_DIR="$(podman volume inspect ublue-os_forge-data | jq -r '.[0].Mountpoint')" +ln -s $FORGE_POD_DATA_DIR $HOME/ublue-os_forge-data +``` + +In that folder you will find an example configuration similar to this: + +```yaml +## ublue-os forge extra-vars example configuration +## For more details got to https://github.com/ublue-os/forge/blob/main/docs/variables.md +--- +forge_git_repository_url: https://github.com/ublue-os/bluefin.git +forge_git_repository_destination: /var/home/stephan/.local/share/containers/storage/volumes/ublue-os_forge-data/_data/data/bluefin +forge_git_repository_version: main +forge_registry_url: registry.ublue.local +``` + +This file acts as a template. Simple copy it and modify it to your liking. For each project +you want to handle with the forge you can create a dedicated file. + +Details about the available variables are documented [here](./variables.md). + +## Usage + +There are two methods of operating the forge, either via a GUI available at +or via [just command runner](https://github.com/casey/just). + +More details about either usage are available here: + +- [GUI](./gui.md) +- [just command runner](./just.md) diff --git a/docs/just.md b/docs/just.md new file mode 100644 index 0000000..38bd128 --- /dev/null +++ b/docs/just.md @@ -0,0 +1,30 @@ +# Usage with just command runner + +If you don't want to use the [GUI](gui.md) we provide the following recipes +via [just command runner](https://github.com/casey/just). + + + +| Just recipe | Input argument | Description | +| --------------------- | ----------------------- | -------------------------------------------- | +| `forge_project-clone` | `forge_config_var_file` | Clone git project repository | +| `forge_project-build` | `forge_config_var_file` | Build container image and upload to registry | + + + +All available settings for the `forge_config_var_file` are documented in the [variables.md](./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 ~/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. diff --git a/docs/variables.md b/docs/variables.md index 5252b53..d415114 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -1,52 +1,23 @@ # 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. +All variables mentioned here can be declared in a yaml configuration file. -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`. +Have a look at the [configuration](./index.md#configuration) chapter for details +on where to find the configuration directory. -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. +The following configuration variables are available and can be set to your liking: -| 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 | +| Name | Type | Default value | Description | +| ---------------------------------- | ---- | ------------------------------------------------- | ---------------------------------------------------------------- | +| `forge_git_repository_url` | str | | Git repository url | +| `forge_git_repository_destination` | str | `{{ forge_data_volume_mountpoint }}`/data/bluefin | Git destination where repository is cloned to.
**_Note:_** | +| `forge_git_repository_version` | str | main | Git repository branch or tag or commit version | +| `forge_registry_url` | str | registry.ublue.local | Container registry url | -## 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. - - - -| name | type | environment variable | default value | description | -| ---------------------------------- | ---- | ---------------------------------- | ----------------------------------------- | ---------------------------------------------- | -| `forge_git_repository_url` | str | `FORGE_GIT_REPOSITORY_URL` | | 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 | - - - -## 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. - - - -| name | type | environment variable | default value | description | -| -------------------- | ---- | -------------------- | -------------------- | ---------------------- | -| `forge_registry_url` | str | `FORGE_REGISTRY_URL` | registry.ublue.local | Container registry url | - - +On playbook launch your variable file will be imported into the ansible container so that +the settings are available during playbook execution.