From 7af09dbc6efcaf597b49107730096b9387a59e4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stephan=20L=C3=BCscher?= Date: Fri, 10 May 2024 19:34:34 +0000 Subject: [PATCH] wip - even more docs (#34) --- README.md | 41 +++++++++++++++++++++++++++++++++-------- docs/gui.md | 6 +++--- docs/index.md | 22 ++++++++++------------ docs/just.md | 7 ++++--- docs/variables.md | 16 ++++++++-------- 5 files changed, 58 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 97cce11..1e76d1b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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. > **Warning** @@ -30,8 +30,8 @@ then made available to all other components and are valid for 2 years and 30 day ### Reverse Proxy -As an entry point for all components we use [Traefik](https://doc.traefik.io/traefik/) as -a reverse proxy. Based on URL routing it will redirect the traffic to the +As an entry point for all web components we use [Traefik](https://doc.traefik.io/traefik/) +as a reverse proxy. Based on URL routing it will redirect the traffic to the right container instance. The reverse proxy dashboard is available at @@ -47,14 +47,39 @@ The container registry API is available at 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 -or via [just command runner](https://github.com/casey/just). +There are two methods of operating the forge, either via a [GUI](./docs/gui.md) available +at 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: diff --git a/docs/gui.md b/docs/gui.md index b2bba0e..22444f7 100644 --- a/docs/gui.md +++ b/docs/gui.md @@ -11,13 +11,13 @@ For navigation you can use the navigation bar on the top left. ### Home 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. ### Ansible -Here you can load your forge configuration file from the data store, -clone a project and build the container image. The buttons should be self explanatory. +Here you can load your forge [configuration](./index.md#configuration) file from the data store, +clone projects and build container images. The buttons should be self explanatory. The "Deploy VM" button is currently a mock-up, sorry :wink: we are [working](https://github.com/ublue-os/forge/issues/35) on it. diff --git a/docs/index.md b/docs/index.md index 6f3fd69..d458820 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ -# Universal Blue - Forge +# Universal Blue - Forge Documentation -On-premises Universal Blue. This projects provides the service units -necessary to set up a self-hosted OS forge for custom images. +On-premises Universal Blue provides the service units necessary to set up a self-hosted +OS forge for custom images. ## 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 ``` +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: ```yaml @@ -51,17 +53,13 @@ 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. +This file acts as a template. It has all available settings outlined for you. 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) +There are two methods of operating the forge, either via a [GUI](./gui.md) available +at or via [just](./just.md) command runner. diff --git a/docs/just.md b/docs/just.md index 38bd128..5859f7d 100644 --- a/docs/just.md +++ b/docs/just.md @@ -1,6 +1,6 @@ # 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). @@ -12,8 +12,9 @@ via [just command runner](https://github.com/casey/just). -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: +The input argument expects a [configuration](./index.md#configuration) file from the data store. + +To launch a recipe you simple run: ```sh just -f forge.just {{ recipe_name }} {{ forge_config_var_file }} diff --git a/docs/variables.md b/docs/variables.md index be982ea..420e36e 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -1,7 +1,7 @@ # Variables -The following sections contains all important variables defined for daily usage. -All variables mentioned here can be declared in a yaml configuration file. +On this page all important variables defined for daily usage are documented. +All variables mentioned here can be declared in a `yaml` configuration file. Have a look at the [configuration](./index.md#configuration) chapter for details on where to find the configuration directory. @@ -10,12 +10,12 @@ The following configuration variables are available and can be set to your likin -| 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. | -| `forge_git_repository_version` | str | main | Git repository branch or tag or commit version | -| `forge_registry_url` | str | registry.ublue.local | Container registry url | +| 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. Can be any directory on your host | +| `forge_git_repository_version` | str | main | Git repository branch or tag or commit version | +| `forge_registry_url` | str | registry.ublue.local | Container registry url |