mirror of
https://github.com/ublue-os/forge.git
synced 2025-07-03 08:21:19 +03:00
wip - docs (#34)
This commit is contained in:
Stephan Lüscher
parent
4f2130bcce
commit
6cdf77b447
39
README.md
39
README.md
|
|
@ -39,7 +39,7 @@ The reverse proxy dashboard is available at <https://traefik.ublue.local>
|
||||||
### Container Registry
|
### Container Registry
|
||||||
|
|
||||||
As container registry we make use of the [Docker Registry 2.0](https://hub.docker.com/_/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 <https://registry.ublue.local/v2>
|
The container registry API is available at <https://registry.ublue.local/v2>
|
||||||
|
|
||||||
|
|
@ -47,11 +47,14 @@ The container registry API is available at <https://registry.ublue.local/v2>
|
||||||
|
|
||||||
The blacksmith's work is done with [Ansible](https://docs.ansible.com/ansible/latest/index.html).
|
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 <https://forge.ublue.local>
|
||||||
|
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
|
## 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.
|
||||||
|
|
||||||
<!-- markdownlint-disable MD013 -->
|
<!-- markdownlint-disable MD013 -->
|
||||||
|
|
||||||
|
|
@ -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 |
|
| `./forge.sh cool-down` | Stop the forge |
|
||||||
|
|
||||||
<!-- markdownlint-enable MD013 -->
|
<!-- markdownlint-enable MD013 -->
|
||||||
|
|
||||||
### Usage
|
|
||||||
|
|
||||||
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 ~/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.
|
|
||||||
|
|
|
||||||
1
docs/gui.md
Normal file
1
docs/gui.md
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
# Usage with GUI
|
||||||
67
docs/index.md
Normal file
67
docs/index.md
Normal file
|
|
@ -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 <https://forge.ublue.local>
|
||||||
|
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)
|
||||||
30
docs/just.md
Normal file
30
docs/just.md
Normal file
|
|
@ -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).
|
||||||
|
|
||||||
|
<!-- markdownlint-disable MD013 -->
|
||||||
|
|
||||||
|
| 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 |
|
||||||
|
|
||||||
|
<!-- markdownlint-enable MD013 -->
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
@ -1,52 +1,23 @@
|
||||||
# Variables
|
# Variables
|
||||||
|
|
||||||
The following sections contains all important variables defined for daily usage.
|
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
|
Have a look at the [configuration](./index.md#configuration) chapter for details
|
||||||
for you. By default it can be found under `$HOME/ublue-os_forge/forge_default_vars.env`.
|
on where to find the configuration directory.
|
||||||
|
|
||||||
On playbook launch the variable file will be imported into the ansible container so that
|
The following configuration variables are available and can be set to your liking:
|
||||||
|
|
||||||
|
<!-- markdownlint-disable MD013 -->
|
||||||
|
|
||||||
|
| Name | Type | Default value | Description |
|
||||||
|
| ---------------------------------- | ---- | ------------------------------------------------- | ---------------------------------------------------------------- |
|
||||||
|
| `forge_git_repository_url` | str | <https://github.com/ublue-os/bluefin.git> | Git repository url |
|
||||||
|
| `forge_git_repository_destination` | str | `{{ forge_data_volume_mountpoint }}`/data/bluefin | Git destination where repository is cloned to. </br> **_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 |
|
||||||
|
|
||||||
|
<!-- markdownlint-enable MD013 -->
|
||||||
|
|
||||||
|
On playbook launch your variable file will be imported into the ansible container so that
|
||||||
the settings are available during playbook execution.
|
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 -->
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue