tec3/ublue-forge
tec3/ublue-forge
1
0
Fork 0
mirror of https://github.com/ublue-os/forge.git synced 2025-04-21 05:53:45 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

wip - even more docs (#34)

Browse source
This commit is contained in:
Stephan Lüscher 2024-05-10 19:34:34 +00:00
parent cbf3c0cb76
commit 7af09dbc6e
No known key found for this signature in database
GPG key ID: 445779060FF3D3CF
5 changed files with 58 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
README.md
View file

@ -1,6 +1,6 @@
# Universal Blue - Forge # Universal Blue - Forge
On-premises Universal Blue. This repository is intended to provide the service units On-premises Universal Blue. This projects intended is to provide the service units
necessary to set up a self-hosted OS forge for custom images. necessary to set up a self-hosted OS forge for custom images.
> **Warning** > **Warning**
@ -30,8 +30,8 @@ then made available to all other components and are valid for 2 years and 30 day
### Reverse Proxy ### Reverse Proxy
As an entry point for all components we use [Traefik](https://doc.traefik.io/traefik/) as As an entry point for all web components we use [Traefik](https://doc.traefik.io/traefik/)
a reverse proxy. Based on URL routing it will redirect the traffic to the as a reverse proxy. Based on URL routing it will redirect the traffic to the
right container instance. right container instance.
The reverse proxy dashboard is available at <https://traefik.ublue.local> The reverse proxy dashboard is available at <https://traefik.ublue.local>
@ -47,14 +47,39 @@ 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).
There are two methods of operating the forge, either via a GUI available at <https://forge.ublue.local> There are two methods of operating the forge, either via a [GUI](./docs/gui.md) available
or via [just command runner](https://github.com/casey/just). at <https://forge.ublue.local> or via [just](./docs/just.md) command runner.
Detailed usage instructions are available in the [documentation](./docs/index.md) section. Details about the project and usage instructions are available in the [documentation](./docs/index.md)
section.
## Handling the forge ## Installation
You can use the `forge.sh` to **setup**, **heat-up** or **cool-down** the forge. ### Pre-requisites
As many tools as possible are built-in but still we rely on some pre-requisites.
These tools and service are necessary to get started:
- [Podman](https://podman.io/)
Must be installed and a [podman socket](https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md)
in the user space must be active.
- [js](https://jqlang.github.io/jq/)
Must be installed. It it currently needed in the setup process to parse certain parameters
automatically for you
- The kernel parameter `net.ipv4.ip_unprivileged_port_start` must be set to `80`
This is because of podman's [shortcoming](https://github.com/containers/podman/blob/main/rootless.md#shortcomings-of-rootless-podman)
to bind to ports `< 1024`. Our reverse-proxy is listening on port `80` and `443`
for incoming traffic.
- [OpenSSH](https://www.openssh.com/)
Must be installed and the service activated. Ansible needs this to execute all the fancy
commands on your host for you.
### Setup / Heat-Up / Cool-Down
For the initial setup and maintenance of the forge you can use the `forge.sh` script:
<!-- markdownlint-disable MD013 --> <!-- markdownlint-disable MD013 -->

6
docs/gui.md
View file

@ -11,13 +11,13 @@ For navigation you can use the navigation bar on the top left.
### Home ### Home
Currently nothing to see here. The goal is to display some Currently nothing to see here. The goal is to display some
general information here. Link to documentation and important general information here. Links to documentation and important
news etc. news etc.
### Ansible ### Ansible
Here you can load your forge configuration file from the data store, Here you can load your forge [configuration](./index.md#configuration) file from the data store,
clone a project and build the container image. The buttons should be self explanatory. clone projects and build container images. The buttons should be self explanatory.
The "Deploy VM" button is currently a mock-up, sorry :wink: The "Deploy VM" button is currently a mock-up, sorry :wink:
we are [working](https://github.com/ublue-os/forge/issues/35) on it. we are [working](https://github.com/ublue-os/forge/issues/35) on it.

22
docs/index.md
View file

@ -1,7 +1,7 @@
# Universal Blue - Forge # Universal Blue - Forge Documentation
On-premises Universal Blue. This projects provides the service units On-premises Universal Blue provides the service units necessary to set up a self-hosted
necessary to set up a self-hosted OS forge for custom images. OS forge for custom images.
## Configuration ## Configuration
@ -39,6 +39,8 @@ FORGE_POD_DATA_DIR="$(podman volume inspect ublue-os_forge-data | jq -r '.[0].Mo
ln -s $FORGE_POD_DATA_DIR $HOME/ublue-os_forge-data ln -s $FORGE_POD_DATA_DIR $HOME/ublue-os_forge-data
``` ```
With this the data folder would be available in your home directory under `~/ublue-os_forge-data`
In that folder you will find an example configuration similar to this: In that folder you will find an example configuration similar to this:
```yaml ```yaml
@ -51,17 +53,13 @@ forge_git_repository_version: main
forge_registry_url: registry.ublue.local forge_registry_url: registry.ublue.local
``` ```
This file acts as a template. Simple copy it and modify it to your liking. For each project This file acts as a template. It has all available settings outlined for you. Simple copy
you want to handle with the forge you can create a dedicated file. 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). Details about the available variables are documented [here](./variables.md).
## Usage ## Usage
There are two methods of operating the forge, either via a GUI available at <https://forge.ublue.local> There are two methods of operating the forge, either via a [GUI](./gui.md) available
or via [just command runner](https://github.com/casey/just). at <https://forge.ublue.local> or via [just](./just.md) command runner.
More details about either usage are available here:
- [GUI](./gui.md)
- [just command runner](./just.md)

7
docs/just.md
View file

@ -1,6 +1,6 @@
# Usage with just command runner # Usage with just command runner
If you don't want to use the [GUI](gui.md) we provide the following recipes 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). via [just command runner](https://github.com/casey/just).
<!-- markdownlint-disable MD013 --> <!-- markdownlint-disable MD013 -->
@ -12,8 +12,9 @@ via [just command runner](https://github.com/casey/just).
<!-- markdownlint-enable MD013 --> <!-- markdownlint-enable MD013 -->
All available settings for the `forge_config_var_file` are documented in the [variables.md](./variables.md) The input argument expects a [configuration](./index.md#configuration) file from the data store.
file. To launch a recipe you simple run:
To launch a recipe you simple run:
```sh ```sh
just -f forge.just {{ recipe_name }} {{ forge_config_var_file }} just -f forge.just {{ recipe_name }} {{ forge_config_var_file }}

16
docs/variables.md
View file

@ -1,7 +1,7 @@
# Variables # Variables
The following sections contains all important variables defined for daily usage. On this page all important variables defined for daily usage are documented.
All variables mentioned here can be declared in a yaml configuration file. All variables mentioned here can be declared in a `yaml` configuration file.
Have a look at the [configuration](./index.md#configuration) chapter for details Have a look at the [configuration](./index.md#configuration) chapter for details
on where to find the configuration directory. on where to find the configuration directory.
@ -10,12 +10,12 @@ The following configuration variables are available and can be set to your likin
<!-- markdownlint-disable MD013 --> <!-- markdownlint-disable MD013 -->
| Name | Type | Default value | Description | | Name | Type | Default value | Description |
| ---------------------------------- | ---- | ------------------------------------------------- | ---------------------------------------------- | | ---------------------------------- | ---- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
| `forge_git_repository_url` | str | <https://github.com/ublue-os/bluefin.git> | Git repository url | | `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. | | `forge_git_repository_destination` | str | `{{ forge_data_volume_mountpoint }}`/data/bluefin | Git destination where repository is cloned to. Can be any directory on your host |
| `forge_git_repository_version` | str | main | Git repository branch or tag or commit version | | `forge_git_repository_version` | str | main | Git repository branch or tag or commit version |
| `forge_registry_url` | str | registry.ublue.local | Container registry url | | `forge_registry_url` | str | registry.ublue.local | Container registry url |
<!-- markdownlint-enable MD013--> <!-- markdownlint-enable MD013-->