mirror of
https://github.com/ublue-os/forge.git
synced 2025-04-21 05:53:45 +03:00
wip - even more docs (#34)
This commit is contained in:
Stephan Lüscher
parent
cbf3c0cb76
commit
7af09dbc6e
41
README.md
41
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 <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).
|
||||
|
||||
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).
|
||||
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.
|
||||
|
||||
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 -->
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <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)
|
||||
There are two methods of operating the forge, either via a [GUI](./gui.md) available
|
||||
at <https://forge.ublue.local> or via [just](./just.md) command runner.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
<!-- markdownlint-disable MD013 -->
|
||||
|
|
@ -12,8 +12,9 @@ via [just command runner](https://github.com/casey/just).
|
|||
|
||||
<!-- 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:
|
||||
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 }}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -11,9 +11,9 @@ The following configuration variables are available and can be set to your likin
|
|||
<!-- 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. |
|
||||
| `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 |
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue