Basic documentation how to obtain the images.

engity-com · Oct 11, 2024 · 3eb9c79 · 3eb9c79
1 parent fb61e5d
commit 3eb9c79
Show file tree

Hide file tree

Showing 3 changed files with 141 additions and 31 deletions.
diff --git a/docs/.theme/marcos/main.py b/docs/.theme/marcos/main.py
@@ -13,14 +13,21 @@
 repo = "engity-com/bifroest"
 repo_http_url = "https://github.com/" + repo
 repo_raw_url = "https://raw.githubusercontent.com/" + repo
+repo_container_uri = "ghcr.io/" + repo
 raw_version = pos.getenv('VERSION')
-release = (("v" if raw_version.__len__() > 0 and raw_version[0].isdigit() else "") +raw_version) if raw_version is not None and raw_version.__len__() > 0 else "latest"
-branch = (("v" if raw_version.__len__() > 0 and raw_version[0].isdigit() else "") +raw_version) if raw_version is not None and raw_version.__len__() > 0 else "main"
+release = (("v" if raw_version.__len__() > 0 and raw_version[0].isdigit() else "") + raw_version) if raw_version is not None and raw_version.__len__() > 0 else "latest"
+branch = (("v" if raw_version.__len__() > 0 and raw_version[0].isdigit() else "") + raw_version) if raw_version is not None and raw_version.__len__() > 0 else "main"
+
+
+class Packaging(str, Enum):
+    archive = 'archive'
+    image = 'image'
 
 class Os(str, Enum):
     linux = 'linux'
     windows = 'windows'
 
+
 class Arch(str, Enum):
     i386 = '386'
     amd64 = 'amd64'
@@ -438,6 +445,23 @@ def flag_with_holder(
             aliases=aliases,
         )
 
+    @env.macro
+    def container_image_uri(
+            tag: str | None = None
+    ) -> str:
+        if tag is not None and tag.find("*") >= 0:
+            if raw_version is not None:
+                tag = tag.replace("*", f"{"-" if tag.find("*") > 0 else ""}{raw_version}")
+            else:
+                tag = tag.replace("*", "")
+
+        return f"{repo_container_uri}{f":{tag}" if tag is not None else ""}"
+
+    @env.macro
+    def container_packages_url() -> str:
+        return f"{repo_http_url}/pkgs/container/bifroest"
+
+
     @env.macro
     def asset_url(file: str, raw: bool = False) -> str:
         if raw:
@@ -519,22 +543,27 @@ def is_image_supported(o: Os | str, arch: Arch | str, kind: EditionKind | str) -
     @env.macro
     def compatibility_matrix(
             os: Os | None = None,
+            packaging: str | Packaging | None = None,
     ) -> str:
+        if type(packaging) is str:
+            packaging = Packaging[packaging]
+
         result = '<table markdown="span" data-kind="compatibility_matrix"><thead markdown="span">'
-        result += '<tr markdown="span"><th rowspan="2">Architecture</th>'
+        result += f'<tr markdown="span"><th{' rowspan="2"' if packaging is None else ''}>Architecture</th>'
         if os is not None:
-            result += f'<th colspan="2">{dist(os)}</th>'
+            result += f'<th{' colspan="2"' if packaging is None else ''} markdown="span">{dist(os)}</th>'
         else:
             for osv in Os:
-                result += f'<th colspan="2" markdown="span">{dist(osv)}</th>'
+                result += f'<th{' colspan="2"' if packaging is None else ''} markdown="span">{dist(osv)}</th>'
         result += "</tr>"
 
-        if os is not None:
-            result += '<th>Binary</th><th>Image</th>'
-        else:
-            for _ in Os:
+        if packaging is None:
+            if os is not None:
                 result += '<th>Binary</th><th>Image</th>'
-        result += '</tr>'
+            else:
+                for _ in Os:
+                    result += '<th>Binary</th><th>Image</th>'
+            result += '</tr>'
 
         result += '</thead><tbody markdown="span">'
 
@@ -544,14 +573,18 @@ def compatibility_matrix(
             if os is not None:
                 generic = support_matrix.lookup(os, arch, EditionKind.generic)
                 extended = support_matrix.lookup(os, arch, EditionKind.extended)
-                result += f'<td markdown="span">{compatibility_editions(True if generic and generic.binary_supported else None, True if extended and extended.binary_supported else None, os)}</td>'
-                result += f'<td markdown="span">{compatibility_editions(True if generic and generic.image_supported else None, True if extended and extended.image_supported else None, os)}</td>'
+                if packaging == Packaging.archive or packaging is None:
+                    result += f'<td markdown="span">{compatibility_editions(True if generic and generic.binary_supported else None, True if extended and extended.binary_supported else None, os)}</td>'
+                if packaging == Packaging.image or packaging is None:
+                    result += f'<td markdown="span">{compatibility_editions(True if generic and generic.image_supported else None, True if extended and extended.image_supported else None, os)}</td>'
             else:
                 for osv in Os:
                     generic = support_matrix.lookup(osv, arch, EditionKind.generic)
                     extended = support_matrix.lookup(osv, arch, EditionKind.extended)
-                    result += f'<td markdown="span">{compatibility_editions(True if generic and generic.binary_supported else None, True if extended and extended.binary_supported else None, osv)}</td>'
-                    result += f'<td markdown="span">{compatibility_editions(True if generic and generic.image_supported else None, True if extended and extended.image_supported else None, osv)}</td>'
+                    if packaging == Packaging.archive or packaging is None:
+                        result += f'<td markdown="span">{compatibility_editions(True if generic and generic.binary_supported else None, True if extended and extended.binary_supported else None, osv)}</td>'
+                    if packaging == Packaging.image or packaging is None:
+                        result += f'<td markdown="span">{compatibility_editions(True if generic and generic.image_supported else None, True if extended and extended.image_supported else None, osv)}</td>'
 
             result += '<tr>'
 

diff --git a/docs/setup/distribution.md b/docs/setup/distribution.md
@@ -1,18 +1,35 @@
 ---
+toc_depth: 4
 description: Which kinds of different distribution are available of Bifröst and how to obtain them.
 ---
 
 # Distributions
 
 Bifröst is available in different distributions.
 
-## Linux {: #linux}
+On this page you'll find:
 
-### Generic {: #linux-generic}
+1. [Operating Systems](#os)
+    1. [Linux](#linux)
+    2. [Windows](#windows)
+2. [Packaging](#packaging)
+    1. [Archives](#archive)
+    2. [OCI/Docker Images](#image)
+
+<<compatibility_matrix()>>
+> Cells express support in format of `<generic>`/`<extended>`.
+
+## Operating Systems {: #os}
+
+Bifröst is currently available for [Linux](#linux) and [Windows](#windows).
+
+### Linux {: #linux}
+
+#### Generic {: #linux-generic}
 
 The generic Linux distribution of Bifröst contains features that run on every Linux distribution, regardless of Ubuntu, Alpine, RedHat, ... It does not even have any requirements on which other shared libraries need to be installed. On the other hand, it lacks some features of the [extended version](#linux-extended).
 
-### Extended {: #linux-extended}
+#### Extended {: #linux-extended}
 
 The extended Linux distribution of Bifröst currently only runs on Debian 12+, Ubuntu 22.04+ and Fedora 39+.
 
@@ -27,41 +44,98 @@ It does provide the following features:
 | [GNU C Library (glibc)](https://www.gnu.org/software/libc/) | `libc.so.6` | 2.34+ |
 | [Linux PAM (Pluggable Authentication Modules for Linux)](https://github.com/linux-pam/linux-pam) | `libpam.so.0` | 1.4+ |
 
-#### Installation
+##### Installation
 
 * **Debian/Ubuntu**: Usually installed by default, in some cases the following command might be necessary:
    ```shell
    sudo apt install libpam0g -y
    ```
 * **RedHat/Fedora**: Already installed by default.
 
-## Windows {: #windows}
+### Windows {: #windows}
 
-### Generic {: #windows-generic}
+#### Generic {: #windows-generic}
 The generic Windows distribution of Bifröst contains all supported features for Windows from Windows 7+ on. It does not even have any requirements on which other shared libraries need to be installed.
 
-### Extended {: #windows-extended}
+#### Extended {: #windows-extended}
 Not available.
 
-## Matrix
+## Packaging
 
-!!! tip ""
-    Cells express support in format of `<generic>`/`<extended>`.
+Bifröst can be either obtained as [Archive which contains the binaries](#archive) or as [OCI/Docker images](#image).
 
-<<compatibility_matrix()>>
+### Archives {: #archive }
+
+Archives contain for every supported operating systems and architecture the binary of Bifröst itself with a basic README, licence information and demo material. It can be simply downloaded, extracted and run.
 
-## Ways to obtain
+See the [release page](<< release_url() >>) for all available downloads.
 
-### Binary
+#### Matrix {: #archive-matrix }
+
+<<compatibility_matrix(packaging="archive")>>
+
+#### URL Syntax {: #archive-syntax }
 
 * Linux:
-    ```shell
-    curl -sSLf <<release_asset_url("bifroest-linux-<arch>-<edition>.tgz")>> | sudo tar -zxv -C /usr/bin bifroest
+    ```plain
+    <<release_asset_url("bifroest-linux-<arch>-<edition>.tgz")>>
     ```
 * Windows:
+    ```plain
+    <<release_asset_url("bifroest-windows-<arch>-<edition>.zip")>>
+    ```
+
+##### Examples {: #archive-examples }
+
+* Linux Extended on AMD64:
+    ```shell
+    curl -sSLf <<release_asset_url("bifroest-linux-amd64-extended.tgz")>> | sudo tar -zxv -C /usr/bin bifroest
+    ```
+
+* Windows Generic on AMD64:
     ```{.powershell title="Run elevated"}
     mkdir -Force 'C:\Program Files\Engity\Bifroest'
     cd 'C:\Program Files\Engity\Bifroest'
-    curl -sSLf -o "${Env:Temp}\bifroest.zip" <<release_asset_url("bifroest-windows-<arch>-<edition>.zip")>>
+    curl -sSLf -o "${Env:Temp}\bifroest.zip" <<release_asset_url("bifroest-windows-amd64-generic.zip")>>
     Expand-Archive "${Env:Temp}\bifroest.zip" -DestinationPath .
     ```
+
+### OCI/Docker Images {: #image}
+
+Bifröst is also available in OCI/Docker images. You just need to mount a valid configuration into the container.
+
+See the [container registry page](<< container_packages_url() >>) for all available tags.
+
+#### Matrix {: #image-matrix }
+
+<<compatibility_matrix(packaging="image")>>
+
+#### TAG Syntax {: #image-syntax }
+
+* Generic:
+    ```plain
+    <<container_image_uri("generic-<major>.<minor>.<patch>")>>
+    <<container_image_uri("generic-<major>.<minor>")>>
+    <<container_image_uri("generic-<major>")>>
+    <<container_image_uri("generic")>>
+    <<container_image_uri("<major>.<minor>.<patch>")>>
+    <<container_image_uri("<major>.<minor>")>>
+    <<container_image_uri("<major>")>>
+    <<container_image_uri("latest")>>
+    ```
+
+* Extended:
+    ```plain
+    <<container_image_uri("extended-<major>.<minor>.<patch>")>>
+    <<container_image_uri("extended-<major>.<minor>")>>
+    <<container_image_uri("extended-<major>")>>
+    <<container_image_uri("extended")>>
+    ```
+
+##### Examples {: #image-examples }
+
+```shell
+<<container_image_uri("*")>>
+<<container_image_uri("latest")>>
+<<container_image_uri("extended")>>
+```
diff --git a/docs/setup/index.md b/docs/setup/index.md
@@ -5,6 +5,9 @@ toc_depth: 2
 
 # Getting started
 
+!!! tip
+     This guide shows how to install Bifröst from [downloadable archive](distribution.md#archive). If you like to use Bifröst inside a container, see our documentation for [OCI/Docker Images](distribution.md#image).
+
 ## Installation
 
 1. Download Bifröst (see [release page](<< release_url() >>)):<br>
@@ -19,7 +22,7 @@ toc_depth: 2
     !!! tip ""
         Cells express support in format of `<generic>`/`<extended>`.
 
-    <<compatibility_matrix()>>
+    <<compatibility_matrix(packaging="archive")>>
 
     #### Example
     ```shell