mirror of
https://github.com/ublue-os/forge.git
synced 2025-07-03 00:11:18 +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
|
||||
|
||||
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>
|
||||
|
||||
|
|
@ -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 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
|
||||
|
||||
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 -->
|
||||
|
||||
|
|
@ -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 |
|
||||
|
||||
<!-- 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
|
||||
|
||||
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 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.
|
||||
|
||||
## 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