Merge branch 'testing' into janhalen-ci-testing

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: ["main"]
+    branches: ["testing"]
   pull_request:
 
 jobs:
@@ -15,8 +15,8 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.1' # Not needed with a .ruby-version file
+          ruby-version: '3.3' # Not needed with a .ruby-version file
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Build with Jekyll
-        run: bundle exec jekyll build
+        run: bundle exec jekyll build

.github/workflows/pages.yml

@@ -1,31 +1,23 @@
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
-# Sample workflow for building and deploying a Jekyll site to GitHub Pages
 name: Deploy Jekyll site to Pages
 
 on:
   push:
-    branches: ["testing"]
+    branches:
+      - main
+      - testing
 
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
-# Allow one concurrent deployment
 concurrency:
   group: "pages"
   cancel-in-progress: true
 
 jobs:
-  # Build job
   build:
     runs-on: ubuntu-latest
     steps:
@@ -34,28 +26,27 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.3' # Not needed with a .ruby-version file
-          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
-          cache-version: 0 # Increment this number if you need to re-download cached gems
+          ruby-version: '3.3'
+          bundler-cache: true
+          cache-version: 0
+
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5
       - name: Build with Jekyll
-        # Outputs to the './_site' directory by default
         run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
         env:
           JEKYLL_ENV: production
       - name: Upload artifact
-        # Automatically uploads an artifact from the './_site' directory by default
         uses: actions/upload-pages-artifact@v3
 
-  # Deployment job
   deploy:
     environment:
       name: github-pages-testing
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
+    environment: ${{ github.ref == 'refs/heads/main' && 'production' || 'testing' }}
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

_config.yml

@@ -1,8 +1,15 @@
-title: Just the Docs Template
-description: A starter template for a Jeykll site using the Just the Docs theme!
+title: OS2 Documentation template
+description: A starter template for an OS2 product documentation build using Jeykll and Just the Docs theme!
 theme: just-the-docs
 
 url: https://just-the-docs.github.io
 
 aux_links:
   Template Repository: https://github.com/just-the-docs/just-the-docs-template
+
+logo: "/assets/images/os2.jpeg"
+
+mermaid:
+  # Version of mermaid library
+  # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
+  version: "10.9.1"

docs/HOW-TO-DEPLOY.MD

@@ -0,0 +1,76 @@
+---
+layout: default
+title: "🚀 How to Deploy"
+---
+
+# 🚀 How to Deploy
+
+## Introduction
+
+Welcome to the deployment guide for [OS2-PROJECTNAME]. This document will walk you through the process of deploying pre-built containers, whether you're setting up a development environment or deploying to a production cluster.
+
+## 💻 Development
+To set up a containerized development and test environment on a local computer or in a hosted developer enviroment like GitHub codespaces, you can use a simple `docker run` or `podman run` command to pull the containerimage and run the container.
+
+#### Docker example
+```shell
+docker run -d -p {CONTAINERPORT:HOSTPORT} --name {CONTAINER_NAME} {IMAGE_NAME}:{TAG}
+```
+[Official documentation for `docker run`](https://docs.docker.com/reference/cli/docker/container/run/)
+
+#### Podman example
+```shell
+podman run -d -p {HOSTPORT}:{CONTAINERPORT} --name {CONTAINER_NAME} {IMAGE_NAME}:{TAG}
+```
+[Official documentation for `podman run`](https://docs.podman.io/en/latest/markdown/podman-run.1.html)
+
+
+
+## 🚢 Production
+To make deployment of [OS2-PROJECTNAME] simple, fast and standardized, we recommend using the supplied deployment templates in the `https://github.com/{USERNAME}/{REPOSITORY}.git` deployment repository. 
+
+### 🖥 Deployment on a single host
+For less demanding production environments on a single VM or bare metal host, you can use tools like Ansible, Chef, or Puppet to deploy the containerimage.
+
+### Examples
+Below is examples that can be run either manually or automated with your Configuration Managment tool of choice. The examples expects the correct enviroment variables to exist and acces to the repository ressources.
+
+### Ansible
+
+Example using `ssh` and `ansible-pull` that pulls and runs the default `local.yml` ansible playbook from the `https://github.com/{USERNAME}/{REPOSITORY}.git` repository.
+
+```shell
+ssh remote_user@remote_host "ansible-pull -U https://github.com/{USERNAME}/{REPOSITORY}.git
+```
+🔗 [Official documentation for `ansible-pull`](https://docs.ansible.com/ansible/latest/cli/ansible-pull.html)
+
+---
+
+### 🌐 Cluster Deployment
+
+For more demanding production environments that require scalability, fault tolerance, enchanced security, observability and high availability it is best practice to deploy [OS2-PROJECTNAME] to a cluster controlled by a container orchestrator with technologies like like [Kubernetes](https://kubernetes.io/), [Nomad](https://www.hashicorp.com/products/nomad) or [OpenShift](https://www.openshift.com/) together with [GitOps](https://opengitops.dev/) tools like [ArgoCD](https://argoproj.github.io/argo-cd/), [Flux](https://fluxcd.io/) or [Fleet](ttps://rancher.com/docs/rancher/v2.x/en/deploy-across-clusters/fleet/ 
+) 
+
+The deployment templates provided in the `https://github.com/{USERNAME}/{REPOSITORY}.git` deployment repository are designed for integration into a version-controlled [GitOps](https://opengitops.dev/) workflow. These templates are compatible with your chosen [GitOps](https://opengitops.dev/) tools and the container orchestrator of your choice.
+
+🔗 [What is GitOps?](https://about.gitlab.com/topics/gitops/)   |  
+🔗 [An illustrated guide to GitOps](https://www.redhat.com/architect/illustrated-guide-gitops)
+
+
+## 🔄 GitOps Process
+Deploy [OS2-PROJECTNAME] to your cluster in 3 steps:
+
+1. **Initialize and Synchronize**: 
+   - **Clone the Deployment Templates**: Start by cloning the deployment templates from `https://github.com/{USERNAME}/{REPOSITORY}.git`.
+   - **Create a New Branch**: Establish a new branch for your modifications to preserve the integrity of the main branch.
+
+2. **Customize and Collaborate**: 
+   - **Customize the Templates**: Tailor the templates to fit your environment and requirements.
+   - **Open a Pull Request (PR)**: Submit a PR for your branch, enabling peer review and collaboration.
+
+3. **Merge and Deploy**: 
+   - **Review and Approve**: Have your team review and approve the PR.
+   - **Merge and Trigger**: Merge the approved PR into the main branch, which triggers the GitOps tool to synchronize and apply the configurations to your cluster.
+
+## ☁️ Managed GitOps Hosting
+If preferred, select a managed GitOps hosting provider that aligns with your project's needs and goals.