tec3/ublue-forge
tec3/ublue-forge
1
0
Fork 0
mirror of https://github.com/ublue-os/forge.git synced 2025-07-10 03:35:47 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: add and enhance documentation for gui, setup and usage (#34)

Browse source
This commit is contained in:
Stephan Lüscher 2024-05-10 22:04:43 +02:00 • committed by GitHub
parent 4f2130bcce
commit 4df5d1667e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 225 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

72
README.md
View file

@ -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 <https://traefik.ublue.local>
@ -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,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 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](./docs/gui.md) available
at <https://forge.ublue.local> or via [just](./docs/just.md) command runner.
## Handling the forge
Details about the project and usage instructions are available in the [documentation](./docs/index.md)
section.
You can use the `forge.sh` to **setup**, **heat-up** and **cool-down** the forge.
## Installation
### 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.
- [jq](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](forge.sh) script:
<!-- markdownlint-disable MD013 -->
@ -63,32 +91,4 @@ You can use the `forge.sh` to **setup**, **heat-up** and **cool-down** 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.
Details about what the setup does can be found [here](./docs/setup.md).