Dokumentacja techniczna

• 1: Epics
• 1.1: Epic 1
• 1.2: Epic 2
• 1.3: Epic 3
• 1.4: Epic 4
• 1.5: Epic 5
• 2: Gitlab Platform
• 2.1: Gitlab-CI
• 2.1.1: Pipelines
• 2.1.1.1: Default
• 2.1.1.2: Gitlab CI
• 2.1.1.3: Gitlab Component
• 2.1.1.4: Image builder
• 2.1.1.5: docs
• 2.1.1.6: opentofu
• 2.1.1.7: opentofu module
• 2.1.1.8: renovate
• 2.1.2: Components
• 2.1.2.1: prepare
• 2.1.2.1.1: 🛠 Job template: Input Parameters
• 2.1.2.1.2: 🛠 Job template: Analyze Conventional Commits
• 2.1.2.2: validate
• 2.1.2.2.1: 🛠 Job template: 🔬 Validate files (conftest)
• 2.1.2.2.2: 🛠 Job template: 🕵 yamllint
• 2.1.2.3: release
• 2.1.2.3.1: 🛠 Job template: Publish Version
• 2.1.2.4: Application Security Testing
• 2.1.2.4.1: 🛠 Job template: 💪 SonarQube Scanner (SAST)
• 2.1.2.4.2: 🛠 Job template: 🔬 Trivy image scan (DAST)
• 2.1.2.5: containers
• 2.1.2.5.1: 🛠 Job template: 🚀 Image bulder
• 2.1.2.6: infrastructure
• 2.1.2.6.1: 🛠 Job template: OpenTofu
• 2.1.2.6.2: 🛠 Job template: Terraform
• 2.1.3: Definicja stages
• 2.1.4: ☠️ Wersjonowanie
• 2.2: 🌐 Gitlab pages
• 2.3: Conventional Commits
• 3: Infrastructure as a Code
• 3.1: Lista konfiguracji
• 3.1.1: IAC-gitlab
• 3.1.1.1: Grupy repozytoriów
• 3.1.1.2: Repozytorium kodu
• 3.2: OpenTofu Modules
• 3.3: Importowanie obiektów
• 3.4: Nadpisanie gitlab states
• 3.5: Integracja z projektem gitlab
• 4: Concepts
• 5: Core Tasks
• 5.1: Bed and Chair Metrics
• 5.2: Porridge Assessment
• 5.3: Another Task
• 5.4: Working with Ponycopters
• 5.4.1: Configuring Ponycopters
• 5.4.2: Launching Ponycopters
• 6: Tutorials
• 6.1: Multi-Bear Domicile Setup
• 6.2: Another Tutorial
• 7: Reference
• 7.1: Parameter Reference
• 8: Contribution Guidelines
• 9: Examples

W tej dokumentacji znajdziesz wszystkie moje pomysły, które są owocem doświadczeń zdobytych podczas realizacji projektów i rozwiązywania problemów technicznych. Każda sekcja jest wynikiem analizy rzeczywistych przypadków, zarówno tych zakończonych sukcesem, jak i tych, które wymagały iteracji i poprawek.

---

Celem tej dokumentacji jest

1. Usprawnienie procesu pracy – Zawiera gotowe rozwiązania, wzorce oraz dobre praktyki, które można łatwo zaadaptować w przyszłych projektach.

2. Zachowanie wiedzy – Wszystkie kluczowe decyzje projektowe, problemy oraz ich rozwiązania są opisane, aby móc do nich wrócić w razie potrzeby.

3. Inspiracja do ulepszeń – Każda sekcja może stanowić punkt wyjścia do optymalizacji i rozwoju istniejących systemów.

---

Znajdziesz tu

• Szczegółowe plany funkcji i modułów.
• Przemyślenia na temat architektury i organizacji kodu.
• Notatki dotyczące integracji narzędzi i technologii.
• Wnioski z błędów i najlepsze praktyki ich unikania.

Ta dokumentacja to kompendium wiedzy, które ewoluuje wraz z nowymi wyzwaniami i pomysłami. Zachęcam do jej eksplorowania, aby w pełni wykorzystać potencjał zawartych tutaj wskazówek i spostrzeżeń.

1 - Epics

flowchart TD
    n1@{ label: "<span style=\"color:\">Przygotowanie środowiska developerskiego</span>" } --> n2["Zarządzenie przestrzenią gitlab za pomocą opentofu"]
    n2 --> n3["Gitlab CI<br>(CI/CD)"]
    n3 --> n4@{ label: "<div style=\"color:\"><span style=\"color:\">Utworzenie centralnego miejsca do przechowywania dokumentacji</span></div>" } & n5["Kontrola Zależności<br>(update depedency renovate)"] & n6["Utworzenie template VM<br>na Proxmox za pomocą<br>Packer"] & n10["Mikrotik IAC"]
    n6 --> n7["Utworzenie playboków dla VM<br>(hardening)"] & n11["Proxmox IAC"]
    n7 --> n8["gitlab-runner<br>"] & n9["Consul + Vault"]
    n11 --> n7
    n10 --> n11
    n3 --> n2

    n1@{ shape: rect}
    n4@{ shape: rect}
    click n1 "/docs/epics/epic1/"
    click n2 "/docs/epics/epic2/"
    click n3 "/docs/epics/epic3/"
    click n4 "/docs/epics/epic4/"
    click n5 "/docs/epics/epic5/"
    click n6 "/docs/epics/epic6/"
    click n7 "/docs/epics/epic7/"

1.1 - Epic 1

Przygotowanie środowiska developerskiego

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
 subgraph s1["Przygotowanie obrazu"]
        n5@{ label: "Przygotowanie maszyny<br style=\"--tw-scale-x:\">wirtualnej na virtualbox" }
        n6@{ label: "<span style=\"padding-left:\">Utworzenie box<br></span><span style=\"padding-left:\">(vagrant package)</span>" }
        n7@{ label: "Wysłanie do<br style=\"--tw-scale-x:\">Vagrant box Registry" }
  end
 subgraph s2["Użycie obrazu (vagrant up)"]
        n8["vagrant up"]
        n9["run bootstrap.bash"]
        n11["bash scripts"]
  end
    n5 --> n6
    n6 --> n7
    s1 --> s2
    n8 --> n9
    s2 --> n10("Ready to use")
    n9 --> n11
    n5@{ shape: rect}
    n6@{ shape: rect}
    n7@{ shape: rect}
    n9@{ shape: lean-r}
    n11@{ shape: procs}

Przygotowanie obrazu

• Utworzenie projektu w Vagrant Box Registries
• Instalacja manualna Ubuntu server 24.10 z użytkownikiem vagrant password vagrant
• Wykonanie skryptu poleceń na koncie vagrant

    sudo apt-get update
    sudo apt-get dist-upgrade -y
    sudo apt install -y openssh-server curl wget sudo
    sudo apt install -y build-essential dkms linux-headers-$(uname -r)
    mkdir -p /home/vagrant/.ssh
    curl -fsSL https://raw.githubusercontent.com/hashicorp/vagrant/master/keys/vagrant.pub -o /home/vagrant/.ssh/authorized_keys
    chown -R vagrant:vagrant /home/vagrant/.ssh
    chmod 700 /home/vagrant/.ssh
    chmod 600 /home/vagrant/.ssh/authorized_keys
    echo "vagrant ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/vagrant
  

• Przygotowanie maszyny wirtualnej do eksportu

  vagrant package --base ubuntu-24.04-base --output ubuntu-24.04.box
  

• Wysłanie obrazu do Vagrant box Registry

Przygotowanie maszyny deweloperskiej

• ✅ Przygotowanie Vagrantfile
• ✅ Przygotowanie skryptu bootstrap
• ✅ Przygotowanie skryptu upgrade-ubuntu.bash
• ✅ Przygotowanie skryptu install-packages.bash
• ✅ Przygotowanie skryptu install-hashicorp.bash

1.2 - Epic 2

Zarządzenie przestrzenią pl.rachuna-net w gitlab za pomocą OpenTofu

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart TD
 subgraph s1["Czynności manualne"]
        n5["Utworzenie grup i repozytoriów<br>"]
  end
 subgraph s2["Utworzenie modułów"]
        n8["gitlab-group"]
        n10["gitlab-project"]
  end
 subgraph s3["Repozytorium IAC"]
        n12["iac-gitlab"]
  end
 subgraph s4["Wykonywanie zmian"]
        n13["tofu plan<br>(wyświetlenie zmian)"]
        n14["tofu apply<br>(Wykonywanie zmian)"]
  end
    s1 --> s2
    n8 --> n12
    n10 --> n12
    n13 --> n14
    n12 --> s4
    n11["Utworzenie obrazu <br>kontenerowego<br>z OpenTofu"] --> s4

    n5@{ shape: rect}
    n12@{ shape: rounded}
    n11@{ shape: rounded}
     n8:::Sky
     n10:::Sky
     n12:::Sky
     n11:::Sky
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    click n8 "https://gitlab.com/pl.rachuna-net/infrastructure/opentofu/modules/gitlab-group"
    click n10 "https://gitlab.com/pl.rachuna-net/infrastructure/opentofu/modules/gitlab-project"
    click n12 "https://gitlab.com/pl.rachuna-net/infrastructure/opentofu/iac-gitlab"
    click n11 "https://gitlab.com/pl.rachuna-net/containers/opentofu"

Manualne tworzenie repozytoriów i grup

• ✅ Utworzenie manualne grupy pl.rachuna-net
• ✅ Utworzenie manualne grupy pl.rachuna-net/infrastructure
• ✅ Utworzenie manualne grupy pl.rachuna-net/infrastructure/opentofu
• ✅ Utworzenie manualne grupy pl.rachuna-net/infrastructure/opentofu/modules
• ✅ Utworzenie manualne repozytorium pl.rachuna-net/infrastructure/opentofu/iac-gitlab
• ✅ Utworzenie manualne repozytorium pl.rachuna-net/infrastructure/opentofu/modules/gitlab-group
• ✅ Utworzenie manualne repozytorium pl.rachuna-net/infrastructure/opentofu/modules/gitlab-project

Moduły OpenTofu

• ✅ Utworzenie modułu zarządzającego grupami gitlab-group → v1.0.0
• ✅ Utworzenie modułu zarządzającego projektami gitlab-project → v1.0.0

Utworzenie obrazu z OpenTofu

• ✅ Utworzenie obrazu z opentofu

podman run -it -v $PWD:/opentofu -v ~/.ssh:/root/.ssh -u root registry.gitlab.com/pl.rachuna-net/containers/opentofu:1.0.0-3d3738b8 bash

cd /opentofu

CI_SERVER_URL="https://gitlab.com"
CI_PROJECT_ID="123456789"
CI_USERNAME="gitlab-runner"
CI_JOB_TOKEN="***"
TF_STATE_NAME="default"

tofu init \
  -backend-config="address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/opentofu/state/${TF_STATE_NAME}" \
  -backend-config="lock_address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/opentofu/state/${TF_STATE_NAME}/lock" \
  -backend-config="unlock_address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/opentofu/state/${TF_STATE_NAME}/lock" \
  -backend-config="username=${CI_USERNAME}" \
  -backend-config="password=${CI_JOB_TOKEN}" \
  -backend-config="lock_method=POST" \
  -backend-config="unlock_method=DELETE" \
  -backend-config="retry_wait_min=5" \
  -lock=false \
  -migrate-state
tofu plan
tofu apply -auto-aprove

Import istniejących zasobów do OpenTofu

tofu import module.group_pl_rachuna-net.gitlab_group.group 105046057

• ✅ Definicja i import grupy pl.rachuna-net
• ✅ Definicja i import grupy pl.rachuna-net/infrastructure
• ✅ Definicja i import grupy pl.rachuna-net/infrastructure/opentofu
• ✅ Definicja i import grupy pl.rachuna-net/infrastructure/opentofu/modules
• ✅ Definicja i import grupy pl.rachuna-net/tools
• ✅ Definicja i import projektu pl.rachuna-net/infrastructure/opentofu/iac-gitlab
• ✅ Definicja i import projektu pl.rachuna-net/infrastructure/opentofu/modules/gitlab-group
• ✅ Definicja i import projektu pl.rachuna-net/infrastructure/opentofu/modules/gitlab-project
• ✅ Definicja i import projektu pl.rachuna-net/tools/vagrant

Utworzenie zasobów do OpenTofu

• ✅ Definicja grupy pl.rachuna-net/containers
• ✅ Definicja i utworzenie repozytorium pl.rachuna-net/containers/opentofu
• ✅ Definicja i utworzenie repozytorium pl.rachuna-net/gitlab-profile
• ✅ Definicja i utworzenie repozytorium pl.rachuna-net/containers/gitlab-profile
• ✅ Definicja i utworzenie repozytorium pl.rachuna-net/infrastructure/opentofu/gitlab-profile

1.3 - Epic 3

Utworzenie procesów gitlab-ci

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
 subgraph s3["Repozytorium IAC"]
        n12["iac-gitlab"]
  end
 subgraph s4["Infrastruktura"]
        n13["Zarządzanie grupami i repozytoriami"]
  end
 subgraph s5["Przestrzeń CI/CD"]
        n18["gitlab-ci"]
        n19["components"]
  end
    n12 --> s4
    n18 --> n19
    n13 -- Definicja pipeline --> s5
    s5 --> n11["containers"]
    n11 --> n22["Job"]

    n12@{ shape: rounded}
    n18@{ shape: rect}
    n19@{ shape: procs}
    n11@{ shape: procs}
    n22@{ shape: lean-r}
     n12:::Sky
     n22:::Pine
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    click n12 "https://gitlab.com/pl.rachuna-net/infrastructure/opentofu/iac-gitlab"

Przygotowanie grup i repozytoriów za pomocą Terraform

- przestrzeń pl.rachuna-net / cicd

• ✅ Definicja grupy pl.rachuna-net/cicd
• ✅ Definicja grupy pl.rachuna-net/cicd/components
• ✅ Definicja repozytorium pl.rachuna-net/cicd/gitlab-profile
• ✅ Definicja repozytorium pl.rachuna-net/cicd/gitlab-ci
• ✅ Definicja repozytorium pl.rachuna-net/cicd/gitlab-rendering
• ✅ Definicja repozytorium pl.rachuna-net/cicd/components/prepare
• ✅ Definicja repozytorium pl.rachuna-net/cicd/components/validate
• ✅ Definicja repozytorium pl.rachuna-net/cicd/components/release
• ✅ Definicja repozytorium pl.rachuna-net/cicd/components/containers
• ✅ Definicja repozytorium pl.rachuna-net/cicd/components/ast
• ✅ Definicja repozytorium pl.rachuna-net/cicd/components/infrastructure

- przestrzeń pl.rachuna-net / containers

• ✅ Definicja repozytorium pl.rachuna-net/containers/buildah
• ✅ Definicja repozytorium pl.rachuna-net/containers/conftest
• ✅ Definicja repozytorium pl.rachuna-net/containers/opentofu
• ✅ Definicja repozytorium pl.rachuna-net/containers/python
• ✅ Definicja repozytorium pl.rachuna-net/containers/semantic-release
• ✅ Definicja repozytorium pl.rachuna-net/containers/trivy

Przygotowanie minimalistycznego procesu do budowania kontenerów (image builder)

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
    A(["Ręczne przygotowanie obrazu konterowego"]) --> B["proces-ci"]
    B --> C@{ label: "<span style=\"color:\">wydanie obrazu</span><br style=\"--tw-scale-x:\"><span style=\"color:\">buildah</span>" } & D["wydanie obrazu<br>semantic-release"] & n2@{ label: "<span style=\"color:\">wydanie obrazu</span><br style=\"--tw-scale-x:\"><span style=\"color:\">python</span>" } & n4@{ label: "<span style=\"padding-left:\"><span style=\"color:\">wydanie obrazu</span><br style=\"--tw-scale-x:\">conftest</span>" } & n5@{ label: "<span style=\"padding-left:\"><span style=\"padding-left:\"><span style=\"color:\">wydanie obrazu<br></span>trivy</span></span>" }
    n1(["Przygotowanie minimalistyczny<br>proces gitlab-ci"]) --> B

    B@{ shape: proc}
    C@{ shape: rect}
    n2@{ shape: rect}
    n4@{ shape: rect}
    n5@{ shape: rect}
     A:::Pine
     n1:::Pine
    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF
    click A "https://gitlab.com/pl.rachuna-net/containers/buildah/-/blob/main/Dockerfile?ref_type=heads"
    click C "https://gitlab.com/pl.rachuna-net/containers/buildah/-/releases/v1.0.0"
    click D "https://gitlab.com/pl.rachuna-net/containers/semantic-release"
    click n2 "https://gitlab.com/pl.rachuna-net/containers/python"
    click n4 "https://gitlab.com/pl.rachuna-net/containers/conftest"
    click n5 "https://gitlab.com/pl.rachuna-net/containers/trivy"
    click n1 "http://localhost:1313/blog/2025/07/23/proces-budowania-kontenerów/#przygotowanie-procesu-ci"

• ✅ Utworzenie obrazu kontenerowego buildah v1.0.0
• ✅ Utworzenie obrazu kontenerowego conftest v1.0.0
• ✅ Utworzenie obrazu kontenerowego python v2.0.0
• ✅ Utworzenie obrazu kontenerowego semantic-release v2.0.0
• ✅ Utworzenie obrazu kontenerowego trivy v1.0.0

Przygotowanie procesu defaultowego procesu

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s1 --> s4

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"

(prepare) Przygotowanie procesu

• ✅ Przygotowanie Joba wyświetlającego dane o procesie 🔍 Input Parameters
• ✅ Przygotowanie Joba wyświetlającego dane o procesie 🔍 Analyze Conventional Commits

(validate) Walidacja

• ✅ Utworzenie Joba z użyciem yamlint 🕵 YAML lint

(release) Wydawnie

• ✅ Przygotowanie Joba Semantic Release 📍 Publish Version

• ✅ 🏁 Wydanie pipeline default → v1.0.0

Przygotowanie procesu dla builder image

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["prepare"]
        n1["🔍 Analyze Conventional Commits"]
        n2["⚙️ Input Parameters"]
        n3["🕵 Set Version"]
  end
 subgraph s2["validate"]
        n4["🧪 Validate files (conftest)"]
        n11@{ label: "<div style=\"color:\"><span style=\"color:\">🧑‍💻 YAML lint</span></div>" }
  end
 subgraph s3["build"]
        n5["🚀 build container image"]
  end
 subgraph s4["publish"]
        n6["🌐 publish container image"]
  end
 subgraph s5["release"]
        n8["📍 Publish Version"]
  end
 subgraph s6["integration-test"]
        n9["🔬 trivy (dast)"]
        n10["🧪 test docker image"]
  end
    s1 --> s2
    s2 --> s3
    s3 --> s4
    s4 --> s5
    s5 --> s6
    n1 --- n2
    n2 --- n3
    n9 --- n10
    n4 --> n11
    n11@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/set_version.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/contrest.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n7 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/vault.yml"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n9 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/trivy.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"

(validate) Walidacja

• ✅ Utworzenie Joba z użyciem conftest 🔬 Validate files (conftest)

(build)

• ✅ Utworzenie Joba z użyciem image-builder 🚀 build container image

(publish) Publikacja

• ✅ Utworzenie Joba z użyciem image-builder 🌐 publish container image

(integration-test) Testy integracyjne

• ✅ Utworzenie Joba z użyciem image-builder 🧪 test docker image

• ✅ Utworzenie Joba z użyciem trivy 🔬 trivy (dast)

• ✅ 🏁 Wydanie pipeline image-builder → v1.0.0

Przygotowanie procesu dla opentofu modules

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
        n8@{ label: "<code><span class=\"hljs-string\">🕵</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu fmt</span></code>" }
        n10@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">tflint</span></code>" }
        n11@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">terraform-docs</span></code>" }
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    n1 --- n8
    n8 --- n10
    n10 --- n11
    s1 --> s3
    n8@{ shape: rect}
    n10@{ shape: rect}
    n11@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"

(validate) Walidacja

• ✅ Przygotowanie Joba 🕵 opentofu fmt
• ✅ Przygotowanie Joba ✅ tflint
• ✅ Przygotowanie Joba ✅ terraform-docs
• ✅ 🏁 Wydanie pipeline opentofu-module → v1.0.0

Przygotowanie procesu dla opentofu

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
        n8@{ label: "<code><span class=\"hljs-string\">🕵</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu fmt</span></code>" }
        n9@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu validate</span></code>" }
        n10@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">tflint</span></code>" }
        n11@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">terraform-docs</span></code>" }
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
 subgraph s5["unit-test"]
        n12@{ label: "<span style=\"color:\" color=\"\">🧪 opentofu plan</span>" }
  end
 subgraph s6["deploy"]
        n13@{ label: "<span style=\"color:\" color=\"\">💥 opentofu apply</span>" }
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s5
    n1 --- n8
    n8 --> n9
    n9 --> n10
    n10 --> n11
    s5 --> s3
    s4 --> s6
    n8@{ shape: rect}
    n9@{ shape: rect}
    n10@{ shape: rect}
    n11@{ shape: rect}
    n12@{ shape: rect}
    n13@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n9 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components//-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n7 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/vault.yml?ref_type=heads"
    click n12 "https://gitlab.com/pl.rachuna-net/cicd/components/unit-test/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n13 "https://gitlab.com/pl.rachuna-net/cicd/components/deploy/-/blob/main/templates/opentofu.yml?ref_type=heads"

• ✅ Przygotowanie Joba ✖️ opentofu validate

• ✅ Przygotowanie Joba 🧪 opentofu plan

• ✅ Przygotowanie Joba 💥 opentofu apply

• ✅ 🏁 Wydanie pipeline opentofu → v1.0.0

1.4 - Epic 4

Utworzenie centralnego miejsca do przechowywania dokumentacji

Zakres prac obejmuje:

• Utworzenie dedykowanych repozytoriów dla dokumentacji i kontenerów wspierających proces publikacji.
• Stworzenie kontenera hugo oraz zautomatyzowanego procesu publikacyjnego.
• Integrację z domeną rachuna-net.pl w celu zapewnienia publicznego dostępu do dokumentacji.
• Integrację GitLab Pages z domeną rachuna-net.pl jako mechanizmu publikacji statycznej dokumentacji.
• Uzupełnienie brakujących sekcji dokumentacyjnych dotyczących projektów infrastrukturalnych, CI/CD oraz kontenerów.
• Realizacja tego epika zapewni ustandaryzowaną, centralną i łatwo dostępną platformę dokumentacyjną wspierającą rozwój oraz utrzymanie systemów i infrastruktury w organizacji.

Przygotowanie grup i repozytoriów za pomocą Terraform

• ✅ Definicja repozytorium pl.rachuna-net/docs
• ✅ Definicja repozytorium pl.rachuna-net/containers/hugo

Przygotowanie kontenera do procesu Gitlab CI

• ✅ Wydanie obrazu kontenerowego gohugo v1.0.0

Przygotowanie procesu CI/CD

• ✅ Stworzenie procesu do publikacji strony z użyciem gitlab pages

Publikacja gitlab-pages i integracja z domeną

• ✅ Integracja z gitlab-pages zbudowane na mkdocs z domeną rachuna-net.pl

1.5 - Epic 5

Renovate

2 - Gitlab Platform

Wstęp do Gitlab Platform

Infrastructure as a Code

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
 subgraph s3["Repozytorium IAC"]
        n12["iac-gitlab"]
  end
 subgraph s4["Infrastruktura"]
        n13["Zarządzanie grupami i repozytoriami"]
  end
    n12 --> s4
    s4 --> n14["Repository"] & n15["Group"]
    n12@{ shape: rounded}
     n14:::Pine
     n15:::Pine
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF

Poniższy schemat opisuje jak wyglada zarządzanie przestrzeńią w gitlabie. Dokładniejszy opis znajduje się tutaj

[Instalacja gitlab-runner](Instalacja Gitlab Runners.md)

Instalacja gitlab-runnera odbywa się za pomocą Terraform, którzy tworzy maszynę wirtualną (container proxmox), a instalacja usługi odbywa się za pomocą Ansible.

Gitlab-CI

W projektach GitLab zaleca się stosowanie centralnego repozytorium z definicjami pipeline’ów oraz wspólnymi komponentami CI/CD, co pozwala na standaryzację i łatwiejsze zarządzanie procesami automatyzacji. Kluczowe znaczenie ma również zachowanie spójnej struktury plików .gitlab-ci.yml, w tym prawidłowa definicja stages, co ułatwia czytelność, utrzymanie i rozwój pipeline’ów w całej organizacji.

2.1 - Gitlab-CI

Infrastruktura procesów gitlab-ci

Pipeline składa się z jobów (zadań) pogrupowanych w stage (etapy), np. build, test, deploy. GitLab CI uruchamia je w określonej kolejności, a wykonanie może odbywać się na GitLab Runnerach – agentach uruchamiających zadania.

Dzięki GitLab CI/CD możliwe jest ciągłe dostarczanie (CD), czyli automatyczne wdrażanie aplikacji na produkcję lub do środowisk testowych. Obsługuje kontenery, chmury i infrastruktury on-premise, ułatwiając zarządzanie cyklem życia oprogramowania.

---
config:
  theme: neo
  layout: dagre
  look: neo
---
flowchart LR
 subgraph s5["Przestrzeń CI/CD"]
        n18["gitlab-ci"]
        n19["components"]
  end
    n18 --> n19
    s5 --> n11["containers"]
    n11 --> n22["Job"]
    n23["Run pipeline"] --> s5
    n24["Event"] --> n23
    n18@{ shape: rect}
    n19@{ shape: procs}
    n11@{ shape: procs}
    n22@{ shape: lean-r}
    n23@{ shape: in-out}
    n24@{ shape: event}
     n22:::Pine
     n23:::Pine
    classDef Aqua stroke-width:1px, stroke-dasharray:none, stroke:#46EDC8, fill:#DEFFF8, color:#378E7A
    classDef Sky stroke-width:1px, stroke-dasharray:none, stroke:#374D7C, fill:#E2EBFF, color:#374D7C
    classDef Pine stroke-width:1px, stroke-dasharray:none, stroke:#254336, fill:#27654A, color:#FFFFFF

Architektura projektu gitlab-ci w pl.rachuna-net/cicd

Projekt zawiera

pl.rachuna-net/cicd
├─ gitlab-ci                 # repozytorium z generycznymi procesami ci
├─ gitlab-profile            # Dokumentacja techniczna
└─ components                # grupa zawierająca komponenty (`ci/cd catalog`)
    ├── ast                  # Komponent do analizy pod kątem bezpiecezństwa (Application Security Testing).
    ├── containers           # Komponent odpowiedzialny za budowanie i publikacje kontenerów.
    ├── infrastructure       # Komponent odpowiedzialny za zarządzanie infrastrukturą.
    ├── prepare              # Komponent do przygotowania procesu CI/CD.
    ├── release              # Komponent do zarządzania wersjami i publikacji bibliotek i aplikacji na środowiska produkcyjne
    └── validate             # Komponent do automatycznej walidacji jakości i poprawności kodu w procesach CI/CD.

Projekt jest podzielony na logiczne komponenty, z których każdy odpowiada za określony etap w procesie CI/CD. Oto główne katalogi i ich funkcje:

• components: Zawiera komponenty odpowiedzialne za różne zadania, takie jak analiza statyczna kodu (SAST), testy jednostkowe, walidacja konfiguracji, budowanie i publikowanie artefaktów.
• gitlab-ci: Zawiera konfiguracje pipeline’ów, w tym pliki YAML definiujące etapy i zadania.
• gitlab-profile: Dokumentacja i skrypty wspierające konfigurację GitLab CI/CD.

Dlaczego taki układ jest korzystny?

Taki podział projektu pl.rachuna-net/cicd zapewnia:

1. Czytelność i modularność

   • Każdy komponent ma jasno określoną odpowiedzialność (np. containers tylko dla kontenerów, validate tylko dla walidacji kodu).
   • Ułatwia to nowym członkom zespołu szybkie odnalezienie się w strukturze – nie muszą przeszukiwać jednego, wielkiego pliku .gitlab-ci.yml.

2. Reużywalność procesów

   • Komponenty działają jak katalog CI/CD – można je wielokrotnie wykorzystywać w różnych projektach.
   • Na przykład prepare lub release mogą być użyte zarówno w projekcie backendowym, jak i frontendowym, bez potrzeby pisania wszystkiego od nowa.

3. Łatwa konserwacja i rozwój

   • Modyfikacja lub poprawka w jednym komponencie (np. ast) nie wpływa bezpośrednio na inne procesy – minimalizuje to ryzyko przypadkowych błędów.
   • Komponenty można rozwijać niezależnie, wprowadzając nowe funkcjonalności w sposób kontrolowany.

4. Skalowalność

   • Wraz z rozwojem organizacji można dodawać kolejne komponenty (np. performance-tests, security-audit) bez przebudowy całej architektury.
   • Każdy komponent może być utrzymywany przez inny zespół lub osobę, co umożliwia równoległy rozwój.

5. Standaryzacja procesów

   • Dzięki centralizacji komponentów wszystkie projekty w organizacji korzystają z tych samych procedur CI/CD, co zwiększa spójność i przewidywalność procesów.
   • Aktualizacja standardów (np. zmiana polityki wersjonowania w release) jest natychmiast dostępna dla wszystkich projektów.

6. Łatwe wdrożenie nowych projektów

   • Aby dodać CI/CD do nowego repozytorium, wystarczy włączyć potrzebne komponenty z katalogu – nie trzeba od zera pisać pipeline’ów.

Wady i ograniczenia takiego układu

Choć architektura oparta na modułowych komponentach CI/CD ma wiele zalet, wiąże się też z pewnymi wyzwaniami. Wymaga dyscypliny w utrzymaniu zgodności wersji komponentów pomiędzy projektami, aby uniknąć sytuacji, w której różne repozytoria korzystają z niekompatybilnych wersji tego samego procesu. Centralizacja logiki powoduje również, że błąd w jednym komponencie może wpłynąć na wiele projektów jednocześnie, jeśli zostanie wdrożony bez odpowiedniego testowania. Dodatkowo w większych organizacjach może pojawić się konieczność koordynacji prac między zespołami rozwijającymi poszczególne komponenty, co może spowalniać wdrażanie zmian.

2.1.1 - Pipelines

Lista pielines

Poniżej znajduje się lista stworzonych procesów

2.1.1.1 - Default

Default

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "hhttps://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

2.1.1.2 - Gitlab CI

gitlab-ci

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "hhttps://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

2.1.1.3 - Gitlab Component

gitlab-component

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "hhttps://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

2.1.1.4 - Image builder

Image builder

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["prepare"]
        n1["🔍 Analyze Conventional Commits"]
        n2["⚙️ Input Parameters"]
        n3["🕵 Set Version"]
  end
 subgraph s2["validate"]
        n4["🧪 Validate files (conftest)"]
        n11@{ label: "<div style=\"color:\"><span style=\"color:\">🧑‍💻 YAML lint</span></div>" }
  end
 subgraph s3["build"]
        n5["🚀 build container image"]
  end
 subgraph s4["publish"]
        n6["🌐 publish container image"]
  end
 subgraph s5["release"]
        n8["📍 Publish Version"]
  end
 subgraph s6["integration-test"]
        n9["🔬 trivy (dast)"]
        n10["🧪 test docker image"]
  end
    s1 --> s2
    s2 --> s3
    s3 --> s4
    s4 --> s5
    s5 --> s6
    n1 --- n2
    n2 --- n3
    n9 --- n10
    n4 --> n11
    n11@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/set_version.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/contrest.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n9 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/trivy.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/containers/-/blob/main/templates/image-builder.yml"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"

2.1.1.5 - docs

docs

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/sast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"

2.1.1.6 - opentofu

OpenTofu

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
        n8@{ label: "<code><span class=\"hljs-string\">🕵</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu fmt</span></code>" }
        n9@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu validate</span></code>" }
        n10@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">tflint</span></code>" }
        n11@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu-docs</span></code>" }
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
 subgraph s5["unit-test"]
        n12@{ label: "<span style=\"color:\" color=\"\">🧪 opentofu plan</span>" }
  end
 subgraph s6["deploy"]
        n13@{ label: "<span style=\"color:\" color=\"\">💥 opentofu apply</span>" }
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s5
    n1 --- n8
    n8 --> n9
    n9 --> n10
    n10 --> n11
    s5 --> s3
    s4 --> s6

    n8@{ shape: rect}
    n9@{ shape: rect}
    n10@{ shape: rect}
    n11@{ shape: rect}
    n12@{ shape: rect}
    n13@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n9 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/ast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n12 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"
    click n13 "https://gitlab.com/pl.rachuna-net/cicd/components/infrastructure/-/blob/main/templates/opentofu.yml?ref_type=heads"

2.1.1.7 - opentofu module

OpenTofu Module

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
        n8@{ label: "<code><span class=\"hljs-string\">🕵</span><span class=\"\"> </span><span class=\"hljs-attr\">opentofu fmt</span></code>" }
        n10@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">tflint</span></code>" }
        n11@{ label: "<code><span class=\"hljs-string\">✅</span><span class=\"\"> </span><span class=\"hljs-attr\">terraform-docs</span></code>" }
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    n1 --- n8
    n8 --- n10
    n10 --- n11
    s1 --> s3
    n8@{ shape: rect}
    n10@{ shape: rect}
    n11@{ shape: rect}
    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n8 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/terraform.yml?ref_type=heads"
    click n10 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/terraform.yml?ref_type=heads"
    click n11 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/terraform.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components//-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/release/-/blob/main/templates/versioning.yml"

2.1.1.8 - renovate

renovate

Gitlab-ci pipeline

---
config:
  theme: redux
---
flowchart LR
 subgraph s1["validate"]
        n1["🧑‍💻 YAML lint"]
  end
 subgraph s2["prepare"]
        n2["🔍 Analyze Conventional Commits"]
        n3["🔍 input parameters"]
        n4["🕵 Set Version"]
  end
 subgraph s3["sast"]
        n5["💪 sonarqube scan"]
  end
 subgraph s4["release"]
        n6["📍 Publish Version"]
  end
    s2 --> s1
    n2 --- n3
    n3 --- n4
    s3 --> s4
    s1 --> s3

    click n1 "https://gitlab.com/pl.rachuna-net/cicd/components/validate/-/blob/main/templates/yamllint.yml?ref_type=heads"
    click n2 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/conventional_commits.yml?ref_type=heads"
    click n3 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n4 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"
    click n5 "https://gitlab.com/pl.rachuna-net/cicd/components/sast/-/blob/main/templates/sonarqube.yml?ref_type=heads"
    click n6 "https://gitlab.com/pl.rachuna-net/cicd/components/prepare/-/blob/main/templates/input_parameters.yml?ref_type=heads"

2.1.2 - Components

Lista komponentów

Poniżej znajduje się lista stworzonych komponentów

component	version
ast
build
deploy
prepare
release
sast
unit-test
validate

2.1.2.1 - prepare

2.1.2.1.1 - 🛠 Job template: Input Parameters

Job, który wyświetla informacje o zmiennych procesowych CI

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe obsługiwane przez skrypt

Komponent wypisuje wartości m.in. następujących zmiennych:

• GITLAB_CI_VERSION
• COMPONENT_VERSION_*
• COMPONENT_VERSION_DEPLOY
• CONTAINER_IMAGE_*
• CONTAINER_IMAGE_PYTHON
• VAULT_ADDR
• SONAR_HOST_URL

📤 Output

Skrypt wypisuje dane w formie tabeli ASCII w logach pipeline’u, np.:

===> 💾 Print set inputs Variables
┌────────────────────────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Variable                       │ Value                                                                                               │
├────────────────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ CONTAINER_IMAGE_TERRAFORM      │ registry.gitlab.com/pl.rachuna-net/containers/terraform:1.0.0                                       │
│ COMPONENT_VERSION_DEPLOY       │ v1.2.3                                                                                              │
...
└────────────────────────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────┘

🧪 Przykład użycia

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/prepare/input_parameters@$COMPONENT_VERSION_PREPARE
    inputs:
      docker_image: $CONTAINER_IMAGE_PYTHON

🔍 input parameters:
  stage: prepare
  rules:
    - when: on_success

2.1.2.1.2 - 🛠 Job template: Analyze Conventional Commits

🔍 Analyze Conventional Commits

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/prepare/conventional_commits@$COMPONENT_VERSION_PREPARE
    inputs:
      docker_image: $CONTAINER_IMAGE_PYTHON

🔍 Analyze Conventional Commits:
  stage: prepare
  rules:
    - when: on_success

2.1.2.2 - validate

2.1.2.2.1 - 🛠 Job template: 🔬 Validate files (conftest)

Wymagania wstępne

• conftest

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_CONFTEST – obraz Dockera Conftest (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• REPOSITORY_POLICIES – repozytorium z politykami
• REPOSITORY_POLICIES_BRANCH – branch repozytorium z politykami
• REPOSITORY_POLICIES_PATH – katalog polityk w repozytorium
• SOURCE_FILES – pliki do testowania
• NAMESPACE_POLICY – przestrzeń nazw polityk Conftest

📤 Output

Job wykonuje następujące kroki:

1. Pobranie logo (jeżeli LOGO_URL jest ustawiony).
2. Wyświetlenie informacji o przekazanych parametrach (_function_print_row).
3. Klonowanie repozytorium z politykami (repository_policies) w odpowiednim branchu.
4. Uruchomienie Conftest z wykorzystaniem wskazanych plików (source_files) i polityk (repository_policies_path) w przestrzeni nazw namespace_policy.

Przykład logu:

===> 🔬 Conftest Validate - Parameters
┌───────────────────────────────────┬─────────────────────────────────────────────────────┐
│ Variable                          │ Value                                               │
├───────────────────────────────────┼─────────────────────────────────────────────────────┤
│ REPOSITORY_POLICIES               │ git@gitlab.com:pl.rachuna-net/discipline.git        │
│ REPOSITORY_POLICIES_PATH          │ policies/conftest                                   │
│ SOURCE_FILES                      │ *.yml                                               │
└───────────────────────────────────┴─────────────────────────────────────────────────────┘

🧪 Dostępne joby

🔬 Validate files (conftest)

Waliduje wskazane pliki repozytorium względem polityk Conftest:

🔬 Validate files (conftest):
  stage: validate
  image: $CONTAINER_IMAGE_CONFTEST
  before_script:
    - git config --global --add safe.directory ${CI_PROJECT_DIR}
    - [ ! -z "${LOGO_URL}" ] && curl -s "${LOGO_URL}"
    - !reference [.validate:_function_print_row]
    - !reference [.validate:conftest_input_variables]
    - !reference [.validate:conftest_prepare]
  script:
    - conftest test $SOURCE_FILES --policy $REPOSITORY_POLICIES_PATH --namespace $NAMESPACE_POLICY

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/validate/conftest@$COMPONENT_VERSION_VALIDATE
    inputs:
      repository_policies: git@gitlab.com:pl.rachuna-net/discipline.git
      repository_policies_path: policies/k8s
      source_files: "config.yml"
      namespace_policy: image_builder

⚡ Dzięki temu szablonowi szybko weryfikujesz zgodność konfiguracji z politykami OPA/Conftest bez ręcznej konfiguracji za każdym razem w pipeline’ach.

2.1.2.2.2 - 🛠 Job template: 🕵 yamllint

Job, który wykonuje walidację składni plików YAML w repozytorium przy użyciu narzędzia yamllint.

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe obsługiwane przez skrypt

Job ustawia i wykorzystuje poniższe zmienne środowiskowe:

• CONTAINER_IMAGE_PYTHON – wybrany obraz Dockera.
• LOGO_URL – adres logotypu, który jest opcjonalnie pobierany w trakcie uruchamiania joba.
• VALIDATE_REPO_NAMESPACE – namespace repozytorium komponentu validate.
• VALIDATE_REPO_BRANCH – gałąź repozytorium komponentu validate.
• YAMLLINT_PATH – ścieżka do pliku konfiguracyjnego yamllint.

📤 Output

Job wykonuje linting plików YAML i wypisuje wyniki w logach pipeline’u w formie standardowej dla narzędzia yamllint, np.:

===> 🔍 YAML lint results
source/ci-template.yml
  10:3      warning  missing document start "---"  (document-start)
  22:1      error    too many blank lines (1 > 0)  (empty-lines)

W przypadku błędów job kończy się statusem failed.

2.1.2.3 - release

2.1.2.3.1 - 🛠 Job template: Publish Version

Wersjonowania kodu

Job, który odpowiada za wersjonowanie i publikację zmian w repozytorium za pomocą narzędzia semantic-release. Szablon składa się z dwóch kroków:

1. 🕵 Set Version – ustawia wersję w trybie dry-run (przygotowanie).
2. 📍 Publish Version – publikuje nową wersję (release).

[!NOTE]

Wymagania:

• Obraz kontenera dostępny jest tutaj.
• Stosowanie standardu opisywania commitów Conventional Commits

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe obsługiwane przez skrypt

Job ustawia i wykorzystuje poniższe zmienne środowiskowe:

• CONTAINER_IMAGE_SEMANTIC_RELEASE – obraz Dockera z semantic-release.
• LOGO_URL – adres logotypu.
• DEBUG – flaga debugowania (dziedziczona z inputs.debug).
• VERSIONING_DEBUG – włącza dodatkowy debug semantic-release.
• VERSIONING_DRY_RUN – uruchamia semantic-release w trybie dry-run.
• COMPONENT_REPO_NAMESPACE – namespace repozytorium komponentu.
• COMPONENT_REPO_BRANCH – gałąź repozytorium komponentu.
• RELEASERC_FILE – ścieżka do pliku .releaserc.js.

📤 Output

Job generuje:

1. Plik CHANGELOG.md – zawierający opis zmian.

2. Plik versioning.env (zapisany jako artifact dotenv) z informacjami o wersji, np.:

   VERSION=1.2.3
   VERSION_MAJOR=1
   VERSION_MINOR=2
   VERSION_PATCH=3
   

3. Logi semantic-release z informacją o wygenerowanej wersji i ewentualnie o publikacji.

📝 Przykładowe użycie w pipeline

include:
  - component: '$CI_SERVER_FQDN/pl.rachuna-net/cicd/components/release@$COMPONENT_VERSION_RELEASE'
    inputs:
      docker_image: "registry.gitlab.com/pl.rachuna-net/containers/semantic-release:2.0.0"
      debug: "true"
      dry_run: "false"

🔎 Kroki joba

🕵 Set Version

• Stage: prepare
• Uruchamia semantic-release w trybie dry-run (VERSIONING_DRY_RUN: "true") w celu przygotowania wersji i changeloga.

📍 Publish Version

• Stage: release
• Uruchamia semantic-release w trybie pełnym (publikacja wersji i generacja changeloga).

Jak działa komponent?

Analiza brancha

W pierwszej kolejności sprawdzane jest - czy można zwersjonować aplikacje na odpowiednim branchu

"branches": [
    { 
      "name": "feature/*", 
      "channel": "feat-${name.replace(/^feature\\//, '').substring(0, 20)}", 
      "prerelease": "feat-${name.replace(/^feature\\//, '').substring(0, 20)}" 
    },
    { 
      "name": "epic/*", 
      "channel": "epic-${name.replace(/^epic\\//, '').replace(/[^A-Za-z0-9]/, '').substring(0, 20)}", 
      "prerelease": "epic-${name.replace(/^epic\\//, '').replace(/[^A-Za-z0-9]/, '').substring(0, 20)}" 
    },
    { "name": "alpha", "channel": "alpha", "prerelease": true },
    { "name": "release", "channel": "rc", "prerelease": true },
    { "name": "hotfix", "channel": "ht", "prerelease": true },
    { "name": "main" }
],

Sprawdzanie convensional commits

Komponent sprawdza, czy czyta wszystkie informacje o commitach zgodnie z standardem Conventional Commits

"plugins": [
[ "@semantic-release/commit-analyzer",
    {
        "preset": "conventionalcommits",
        "releaseRules": [
            { "breaking": true, "release": "major" },
            { "type": "feat", "release": "minor" },
            { "type": "fix", "release": "patch" },
            { "type": "style", "release": "patch" },
            { "type": "perf", "release": "patch" },
            { "type": "test", "release": "patch" },
            { "type": "docs", "release": "patch" },
            { "type": "sec", "release": "patch" }
        ]
    }
],

Generowanie releases notes

Następnie generuje release notes

[
    "@semantic-release/release-notes-generator",
    {
        "preset": "conventionalcommits",
        "presetConfig": {
            "types": [
              { "type": "feat", "section": "✨ Features ✨" },
              { "type": "fix", "section": "🐛 Bug Fixes 🐛" },
              { "type": "revert", "section": "⏮️️ Reverts ⏮️️" },
              { "type": "perf", "section": "🔧 Performance Improvements 🔧" },
              { "type": "docs", "section": "📝 Documentation 📝" },
              { "type": "build", "section": "📀 Build 📀" },
              { "type": "test", "section": "💚 Tests 💚" },
              { "type": "ci", "section": "🏁 CI/CD 🏁" }
            ]
        }
    }
],

Generowanie chandelog.md

Generowanie localnie pliku CHANGELOG.md

[
    "@semantic-release/changelog",
    {
      "changelogFile": "CHANGELOG.md"
    }
],

Integracja z gitlab

Integracja z gitab

[
    "@semantic-release/gitlab"
]

Ustawienie zmiennych środowiskowych

{
  name: "versioning-variables",
  generateNotes: (pluginConfig, context) => {
    const releaseNote = context.nextRelease.notes;
    const nextVersion = context.nextRelease.version;

    // Check if the version is a final version or a snapshot
    const finalVersionRegex = /(\d+\.\d+\.\d+)/;
    const matchFinalVersion = nextVersion.match(finalVersionRegex);
    let artifactType = "snapshot";
    if (matchFinalVersion) {
      artifactType = "release";
    }

    // Extract JIRA issues from commits
    const jiraRegexp = /\b[A-Z][A-Z0-9_]+-[1-9][0-9]*/g;
    const jiraSet = new Set();

    for (const commit of context.commits) {
      if (commit.message) {
        const matchJIRA = commit.message.match(jiraRegexp);
        if (matchJIRA) {
          matchJIRA.forEach(jira => jiraSet.add(match));
        }
      }
    }

    // Create a file with the environment variables
    const uniqJiraList = Array.from(jiraSet)
    const environmentList = [
      { key: "RELEASE_CANDIDATE_VERSION", value: nextVersion },
      { key: "ARTIFACTS_TYPE", value: artifactType },
      { key: "JIRA_ISSUES_IDS", value: uniqJiraList.join(", ") }
    ]
    const fileContent = environmentList.map(env => `${env.key}=${env.value}`).join("\n");
    fs.writeFileSync("versioning.env", fileContent);
  }
}

Linki

• SemVer
• semantic-release

2.1.2.4 - Application Security Testing

- Application Security Testing

2.1.2.4.1 - 🛠 Job template: 💪 SonarQube Scanner (SAST)

Wymagania wstępne

• SonarQube Scanner – dostępny w obrazie Dockera ustawianym przez inputs.docker_image.
• Skonfigurowane konto w SonarCloud lub własnej instancji SonarQube (parametry: sonar_host_url, sonar_token, sonar_project_key).

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_SONAR_SCANNER – obraz Dockera SonarQube Scanner (na podstawie inputs.docker_image)
• SONAR_USER_HOME – katalog roboczy SonarQube
• SONAR_HOST_URL – adres instancji SonarQube/SonarCloud
• SONAR_ORGANIZATION – nazwa organizacji
• SONAR_PROJECT_KEY – klucz projektu w SonarQube
• SONAR_PROJECT_NAME – nazwa projektu
• SONAR_PROJECT_DESCRIPTION – opis projektu
• SONAR_PROJECT_VERSION – wersja projektu
• SONAR_SOURCES – ścieżki źródeł do analizy
• SONAR_TOKEN – token uwierzytelniający do SonarQube

📤 Output

Job wykonuje następujące kroki:

2. Wyświetlenie zmiennych wejściowych i konfiguracji SonarQube.

3. Uruchomienie SonarQube Scanner z zadeklarowanymi parametrami:

   • analiza kodu z podanych źródeł (SONAR_SOURCES),
   • przesłanie wyników do wskazanej instancji (SONAR_HOST_URL).

Pipeline zakończy się niepowodzeniem, jeśli analiza SonarQube wykryje błędy jakościowe powodujące blokadę (quality gate failure).

🧪 Dostępny job

💪 sonarqube scanner (sast)

Analizuje kod źródłowy i przesyła wyniki do SonarQube/SonarCloud:

💪 sonarqube scanner:
  stage: sast
  image: $CONTAINER_IMAGE_SONAR_SCANNER
  before_script:
    - git config --global --add safe.directory ${CI_PROJECT_DIR}
    - [ ! -z "${LOGO_URL}" ] && curl -s "${LOGO_URL}"
    - !reference [.ast:_function_print_row]
    - !reference [.ast:sonarqube_input_variables]
    - !reference [.ast:sonarqube-init]
  script:
    - |
      sonar-scanner \
        -Dsonar.projectKey="${SONAR_PROJECT_KEY}" \
        -Dsonar.organization="${SONAR_ORGANIZATION}" \
        -Dsonar.projectName="${SONAR_PROJECT_NAME}" \
        -Dsonar.projectDescription="${CI_PROJECT_DESCRIPTION}" \
        -Dsonar.projectVersion="${SONAR_PROJECT_VERSION}" \
        -Dsonar.sources="${SONAR_SOURCES}" \
        -Dsonar.sourceEncoding=UTF-8 \
        -Dsonar.token="${SONAR_TOKEN}"
  rules:
    - when: on_success

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/ast/sonarqube@$COMPONENT_VERSION_SONARQUBE

💪 sonarqube scanner:
  variables:
    SONAR_PROJECT_KEY: $CI_PROJECT_NAME
    SONAR_PROJECT_NAME: "Project $CI_PROJECT_NAME"
    SONAR_TOKEN: $SONAR_TOKEN
  rules:
    - when: on_success

2.1.2.4.2 - 🛠 Job template: 🔬 Trivy image scan (DAST)

Wymagania wstępne

• Trivy – wbudowany w używany obraz Dockera (ustawiany przez inputs.docker_image).
• Obraz kontenera, który ma zostać przeskanowany (ustawiany przez inputs.container_to_analyze).

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_TRIVY – obraz Dockera Trivy (na podstawie inputs.docker_image)
• CONTAINER_TO_ANALYZE – nazwa obrazu kontenera do przeskanowania (na podstawie inputs.container_to_analyze)
• TRIVY_NO_PROGRESS – wyłącza pasek postępu w logach (domyślnie true)
• TRIVY_CACHE_DIR – lokalny katalog cache Trivy (domyślnie .trivycache/)

📤 Output

Job wykonuje następujące kroki:

1. Uruchomienie skanowania obrazu kontenera (CONTAINER_TO_ANALYZE) z użyciem Trivy:

   • Najpierw wyszukiwanie luk o poziomie HIGH – raport ostrzegawczy (--exit-code 0).
   • Następnie wyszukiwanie luk o poziomie CRITICAL – pipeline zakończy się niepowodzeniem, jeśli takie wystąpią (--exit-code 1).

2. Wykorzystanie cache Trivy w katalogu .trivycache/ w celu przyspieszenia kolejnych skanów.

🧪 Dostępny job

🔬 trivy (dast)

Skanuje wskazany obraz kontenera i kończy pipeline, jeśli znajdzie luki o poziomie CRITICAL:

🔬 trivy (dast):
  image: $CONTAINER_IMAGE_TRIVY
  stage: integration-test
  services:
    - name: $CONTAINER_IMAGE_TRIVY
      alias: buildah-dind
  allow_failure: true
  before_script:
    - git config --global --add safe.directory ${CI_PROJECT_DIR}
    - [ ! -z "${LOGO_URL}" ] && curl -s "${LOGO_URL}"
    - !reference [.ast:trivy_input_variables]
  script:
    - trivy image --exit-code 0 --severity HIGH $CONTAINER_TO_ANALYZE
    - trivy image --exit-code 1 --severity CRITICAL $CONTAINER_TO_ANALYZE
  cache:
    paths:
      - .trivycache/

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/ast/trivy@$COMPONENT_VERSION_TRIVY

🔬 trivy (dast):
  allow_failure: true
  variables:
    CONTAINER_TO_ANALYZE: $CI_REGISTRY_IMAGE:$RELEASE_CANDIDATE_VERSION
  rules:
    - when: on_success

2.1.2.5 - containers

2.1.2.5.1 - 🛠 Job template: 🚀 Image bulder

Wymagania wstępne

• Buildah – wbudowany w używany obraz Dockera (ustawiany przez inputs.docker_image).
• Dostęp do rejestru Docker/GitLab (CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORD).
• Plik konfiguracyjny obrazu kontenera (buildah_config_path).

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobie

• CONTAINER_IMAGE_BUILDAH – obraz Dockera Buildah (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• CONTAINER_VERSION – wersja obrazu (na podstawie inputs.container_version)
• FULL_IMAGE_NAME – pełna nazwa obrazu: $CI_REGISTRY_IMAGE:$CONTAINER_VERSION
• BUILDAH_CONFIG_FILE_PATH – ścieżka do pliku konfiguracji Buildah (na podstawie inputs.buildah_config_path)
• DOCKER_TEST_SCRIPT_PATH – skrypt testowy do uruchomienia w kontenerze
• Dodatkowe zmienne konfiguracyjne Buildah: STORAGE_DRIVER, BUILDAH_FORMAT, BUILDAH_ISOLATION, BUILDAH_STORAGE_ROOT, BUILDAH_STORAGE_RUNROOT

📤 Output

Szablon wykonuje następujące kroki:

1. Budowanie obrazu kontenera na podstawie buildah_config_path:

   • Pobranie obrazu bazowego (base_image)
   • Instalacja pakietów i certyfikatów
   • Dodanie repozytoriów (custom_repos)
   • Kopiowanie plików i ustawienie zmiennych środowiskowych
   • Tworzenie użytkownika nie-root (opcjonalnie)
   • Ustawienie ENTRYPOINT oraz CMD

2. Zapis obrazu do tarballa (container-image.tar).

3. Publikacja obrazu w rejestrze Docker/GitLab (job 🌐 publish container image).

4. Testowanie obrazu z wykorzystaniem skryptu testowego (job 🧪 test docker image).

🧪 Dostępne joby

🚀 build container image

Buduje obraz kontenera na podstawie pliku konfiguracyjnego config.yml

Przykładowy plik config yml:

---
base_image: ubuntu:noble

labels:
  maintainer: "Maciej Rachuna <rachuna.maciej@gmail.com>"
  version: "1.0.0"
  image_source: "https://gitlab.com/pl.rachuna-net/containers/terraform"

env:
  DEBIAN_FRONTEND: noninteractive
  TF_IN_AUTOMATION: "true"
  LANG: C.UTF-8

before_build_commands:
  ## terraform docs
  - curl -sLo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.20.0/terraform-docs-v0.20.0-linux-amd64.tar.gz
  - tar -xzf terraform-docs.tar.gz
  - chmod +x terraform-docs
  ## terraform lint
  - curl -sLo ./tflint_linux_amd64.zip https://github.com/terraform-linters/tflint/releases/download/v0.58.1/tflint_linux_amd64.zip
  - unzip tflint_linux_amd64.zip
  - chmod +x tflint

packages:
  - bash
  - curl
  - git
  - gnupg2
  - jq
  - libssl3
  - lsb-release
  - openssh-client
  - ca-certificates
  - gnupg
  - terraform

custom_repos:
  - name: hashicorp
    key_url: https://apt.releases.hashicorp.com/gpg
    key_path: /usr/share/keyrings/hashicorp-archive-keyring.gpg
    repo_entry: >-
      deb [arch=amd64 signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg trusted=yes] https://apt.releases.hashicorp.com noble main

extra_commands:
  - chmod 777 /opt/scripts
  - chmod 777 /opt/scripts/*
  - terraform --version
  - terraform-docs -v
  - tflint --version

copy:
  - source: scripts/
    destination: /opt/scripts/
  - source: terraform-docs
    destination: /usr/local/bin/terraform-docs
  - source: tflint
    destination: usr/local/bin/tflint

user:
  name: nonroot
  shell: /bin/bash
  home: /home/nonroot
  chown: /opt/scripts/

entrypoint: "/opt/scripts/entrypoint.bash"
cmd: "/bin/bash"

🌐 publish container image

Publikuje zbudowany obraz do gitlab registry:

🧪 test docker image

Testuje opublikowany obraz kontenera uruchamiając w nim skrypt bashowy domyślnie container_test.sh:

🧪 Przykład użycia w pipeline

---
default:
  tags:
    - process-ci

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/containers/image-builder@$COMPONENT_VERSION_CONTAINERS


🚀 build container image:
  needs:
    - job: 🕵 YAML lint
      optional: true
    - job: 🔬 Validate files (conftest)
    - job: 🕵 Set Version
      artifacts: true
  stage: build
  rules:
    - when: on_success


🌐 publish container image:
  stage: publish
  variables:
    CONTAINER_VERSION: 1.2.3
  needs:
    - job: 🕵 Set Version
      artifacts: true
    - job: 🚀 build container image
      artifacts: true
  rules:
    - when: on_success


🧪 test docker image:
  variables:
    CONTAINER_VERSION: 1.2.3
  needs:
    - job: 📍 Publish Version
      artifacts: true
    - job: 🌐 publish container image
      artifacts: true
  rules:
    - when: on_success

2.1.2.6 - infrastructure

2.1.2.6.1 - 🛠 Job template: OpenTofu

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobach

Komponent ustawia następujące zmienne w środowisku CI:

• CONTAINER_IMAGE_OPENTOFU – obraz Dockera OpenTofu (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• TF_STATE_NAME – nazwa stanu OpenTofu
• TF_VAR_gitlab_token – token GitLab przekazywany do OpenTofu
• DEBUG – flaga debug

📤 Output

Joby wykonują:

1. Pobranie i wyświetlenie logo (jeżeli LOGO_URL jest ustawiony).
2. Wyświetlenie informacji o wejściowych parametrach.
3. Inicjalizację środowiska OpenTofu (tofu init) oraz odpowiednie akcje (fmt, validate, tflint, plan, apply).

Przykład logu:

===> 💾 OpenTofu Base Job - Parameters
┌──────────────────────────────┬───────────────────────────────────────────────────────┐
│ Variable                     │ Value                                                 │
├──────────────────────────────┼───────────────────────────────────────────────────────┤
│ TF_STATE_NAME                │ default                                               │
│ CONTAINER_IMAGE_OPENTOFU     │ registry.gitlab.com/pl.rachuna-net/...:2.0.0          │
└──────────────────────────────┴───────────────────────────────────────────────────────┘

🧪 Dostępne joby

🕵 opentofu fmt

Sprawdza formatowanie plików OpenTofu:

🕵 opentofu fmt:
  stage: validate
  extends: ['.infrastructure:opentofu:base']
  script:
    - tofu fmt -recursive -check

✅ opentofu validate

Wykonuje walidację konfiguracji OpenTofu:

✅ opentofu validate:
  stage: validate
  extends: ['.infrastructure:opentofu:base']
  script:
    - !reference [.infrastructure:opentofu_init]
    - tofu validate

✅ tflint

Uruchamia lintera tflint:

✅ tflint:
  stage: validate
  extends: ['.infrastructure:opentofu:base']
  script:
    - tflint

✅ terraform-docs

Generuje dokumentację modułu Terraform:

✅ terraform-docs:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform-docs md . > README.md

🧪 opentofu plan

Wykonuje plan wdrożenia OpenTofu:

🧪 opentofu plan:
  stage: unit-test
  extends: ['.infrastructure:opentofu:base']
  script:
    - tofu plan

💥 opentofu apply

Wdraża infrastrukturę OpenTofu:

💥 opentofu apply:
  stage: deploy
  extends: ['.infrastructure:opentofu:base']
  script:
    - tofu apply -auto-approve

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/infrastructure/opentofu@$COMPONENT_VERSION_INFRASTRUCTURE
    inputs:
      docker_image: $CONTAINER_IMAGE_OPENTOFU
      tf_state_name: production
      debug: "true"

2.1.2.6.2 - 🛠 Job template: Terraform

⚙️ Parametry wejściowe (inputs)

🧬 Zmienne środowiskowe ustawiane w jobach

Komponent ustawia następujące zmienne w środowisku CI:

• CONTAINER_IMAGE_TERRAFORM – obraz Dockera Terraform (na podstawie inputs.docker_image)
• LOGO_URL – ścieżka do logo (na podstawie inputs.logo_url)
• TF_STATE_NAME – nazwa stanu Terraform
• TF_VAR_gitlab_token – token GitLab przekazywany do Terraform
• DEBUG – flaga debug

📤 Output

Joby wykonują:

1. Pobranie i wyświetlenie logo (jeżeli LOGO_URL jest ustawiony).
2. Wyświetlenie informacji o wejściowych parametrach.
3. Inicjalizację środowiska Terraform (terraform init) oraz odpowiednie akcje (fmt, validate, tflint, plan, apply).

Przykład logu:

===> 💾 Terraform Base Job - Parameters
┌──────────────────────────────┬───────────────────────────────────────────────────────┐
│ Variable                     │ Value                                                 │
├──────────────────────────────┼───────────────────────────────────────────────────────┤
│ TF_STATE_NAME                │ default                                               │
│ CONTAINER_IMAGE_TERRAFORM    │ registry.gitlab.com/pl.rachuna-net/...:2.0.0          │
└──────────────────────────────┴───────────────────────────────────────────────────────┘

🧪 Dostępne joby

🕵 terraform fmt

Sprawdza formatowanie plików Terraform:

🕵 terraform fmt:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform fmt -recursive -check

✅ terraform validate

Wykonuje walidację konfiguracji Terraform:

✅ terraform validate:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - !reference [.infrastructure:terraform_init]
    - terraform validate

✅ tflint

Uruchamia lintera tflint:

✅ tflint:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - tflint

✅ terraform-docs

Generuje dokumentację modułu Terraform:

✅ terraform-docs:
  stage: validate
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform-docs md . > README.md

🧪 terraform plan

Wykonuje plan wdrożenia Terraform:

🧪 terraform plan:
  stage: unit-test
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform plan

💥 terraform apply

Wdraża infrastrukturę Terraform:

💥 terraform apply:
  stage: deploy
  extends: ['.infrastructure:terraform:base']
  script:
    - terraform apply -auto-approve

🧪 Przykład użycia w pipeline

include:
  - component: $CI_SERVER_FQDN/pl.rachuna-net/cicd/components/infrastructure/terraform@$COMPONENT_VERSION_INFRASTRUCTURE
    inputs:
      docker_image: $CONTAINER_IMAGE_TERRAFORM
      tf_state_name: production
      debug: "true"

2.1.3 - Definicja stages

Definicja stages

Przykładowa zawartość pliku:

---
stages:
    ### Standard w ramach dyscypliny
    - prepare           # przygotowanie środowiska, instalacja zależności, inicjalizacja.
    - dependency        # pobieranie zależności (biliotek, funkcji, komponentów)
    - validate          # weryfikacja poprawności konfiguracji, linting, planowanie zmian (Terraform, Ansible), pre-commit checks.
    - unit-test         # testy jednostkowe dla kodu (Go, .NET, Node.js itp.).
    - sast              # analiza statyczna kodu (Static Application Security Testing).
    - dast              # analiza dynamiczna aplikacji (Dynamic Application Security Testing).
    - build             # budowanie artefaktów (Packer, kontenery, kod źródłowy).
    - publish           # publikacja artefaktów, obrazów kontenerowych, paczek NuGet, npm itp.
    - release           # Wydawanie wersji
    - deploy            # wdrażanie aplikacji, infrastruktury, konfiguracji.
    - integration-test  # testy integracyjne, e2e, testy akceptacyjne.
    - cleanup           # usuwanie tymczasowych zasobów, sprzątanie środowiska.

2.1.4 - ☠️ Wersjonowanie

Definicja stages

Racja – poprzednia odpowiedź była bardziej ogólna niż powinna. Skupmy się teraz na technicznej dokumentacji wersjonowania dokładnie w kontekście Twojego rysunku. Oto spójny opis, który możesz wkleić do dokumentacji:

Wersjonowanie w projekcie

W projekcie wykorzystujemy semantic-release do w pełni zautomatyzowanego nadawania wersji, tagowania oraz generowania changeloga. Proces opiera się na strukturze gałęzi main / develop / feature oraz na konwencji commitów (Conventional Commits).

1. Gałęzie w repozytorium

1. main – zawiera stabilne wydania produkcyjne.

   • Każdy merge z develop powoduje wygenerowanie pełnego release (1.0.0, 1.1.0 itd.).

2. develop – zawiera kod przeznaczony do testów wewnętrznych.

   • Każdy merge z gałęzi feature powoduje wygenerowanie pre-release (1.1.0-dev.1, 1.1.0-dev.2 itd.).

3. Gałęzie funkcjonalne (feat/<JIRA-ID>) – zawierają zmiany pojedynczych funkcjonalności.

   • Nie generują wersji samodzielnie.
   • Wersja jest podbijana dopiero po merge do develop.

2. Jak semantic-release nadaje wersje?

• Semantic-release analizuje commity od ostatniego taga.

• Na podstawie typów commitów automatycznie decyduje o nowej wersji:

  • fix: / chore: – patch (np. 1.0.0 → 1.0.1)
  • feat: – minor (np. 1.0.0 → 1.1.0)
  • BREAKING CHANGE: – major (np. 1.0.0 → 2.0.0)

• Dla develop każda zmiana jest oznaczana jako pre-release z przyrostowym numerem dev:

  1.1.0-dev.1
  1.1.0-dev.2
  

• Merge develop → main tworzy pełny release:

  1.1.0
  

3. Przykład na podstawie diagramu

1. Tag 1.0.0 istnieje na gałęzi main.

2. Tworzymy gałąź develop – kolejne zmiany są tu wersjonowane jako pre-release:

   • Merge feat/JIRA-1234 → develop: wersja 1.1.0-dev.1
   • Merge feat/JIRA-2345 → develop: wersja 1.1.0-dev.2

3. Gdy kod na develop jest stabilny:

   • Merge do main → semantic-release tworzy pełny release: wersja 1.1.0 oraz changelog.

4. Konfiguracja (.releaserc)

{
  "branches": [
    "main",
    { "name": "develop", "prerelease": "dev" }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/gitlab"
  ]
}

• Gałąź main generuje pełne wydania.
• Gałąź develop generuje pre-release z dopiskiem -dev.X.

Czy chcesz, żebym przygotował wersję dokumentacji z diagramem w SVG/PNG, gdzie będzie oznaczony każdy krok (merge, tag, pre-release)? Mogę też dodać sekcję o commitach (wzorce feat, fix itd.) albo schemat krok-po-kroku pipeline’u CI/CD (np. GitLab CI). Chcesz, żeby to była pełna sekcja “Wersjonowanie” w stylu dokumentacji technicznej projektu?

gitGraph
        commit id: "latest" tag: "1.0.0"
        branch "develop"
        branch "feat/JIRA-1234"
        branch "feat/JIRA-2345"
        checkout "develop"
        checkout "feat/JIRA-1234"
        commit id: "feat: JIRA-1234"
        checkout develop
        merge "feat/JIRA-1234" id: "FEAT-1234" tag: "1.1.0-dev.1"
        checkout main
        checkout "feat/JIRA-2345"
        commit id: "fix: JIRA-2345"
        checkout develop
        merge "feat/JIRA-2345"  id: "FEAT-2345" tag: "1.1.0-dev.2"
        checkout main
        merge "develop" id: "New Version" tag: "1.1.0"

gitGraph
        commit id: "latest" tag: "1.0.0"
        branch "develop"
        branch "feat/JIRA-1234"
        branch "feat/JIRA-2345"
        checkout "develop"
        checkout "feat/JIRA-1234"
        commit id: "feat: JIRA-1234"
        checkout develop
        merge "feat/JIRA-1234" id: "FEAT-1234" tag: "1.0.0-dev.1"
        checkout main
        checkout "feat/JIRA-2345"
        commit id: "feat: JIRA-2345"
        checkout develop
        merge "feat/JIRA-2345"  id: "FEAT-2345" tag: "1.0.0-dev.2"
        checkout main
        merge "develop" id: "New Feat" tag: "1.1.0"
        branch "hotfix"
        checkout "hotfix"
        commit id: "fix: JIRA-9999"
        checkout main
        merge "hotfix" id: "Hotfix" tag: "1.1.1"

2.2 - 🌐 Gitlab pages

🌐 Gitlab pages

Wymagania

• GitLab repository z plikami markdown zgodnymi z framweork gohugo i template docsy
• Dostęp do panelu zarządzania DNS

1. Przygotowanie repozytorium z dokumentacją

1. Zainicjalizuj projekt MkDocs (jeśli jeszcze nie istnieje):

   hugo new my-project
   cd my-project
   

2. Dodaj plik .gitlab-ci.yml do repozytorium:

   image: $CONTAINER_IMAGE_GOHUGO
   
   🚀 build gohugo project:
   stage: build
   script:
      - npm install
      - hugo
   artifacts:
      paths:
         - public
   rules:
      - when: on_success
   
   pages:
      stage: deploy
      dependencies:
         - 🚀 build gohugo project
      script:
         - echo "publish pages"
      pages: true
      rules: !reference [.rule:deploy:gohugo, rules]
      environment:
         name: Production
         url: https://$CI_PROJECT_NAMESPACE.gitlab.io/
   only:
      - main
   

3. Wypchnij zmiany do GitLaba:

   git add .
   git commit -m "Init hugo site"
   git push origin main
   

4. Po chwili strona powinna być dostępna pod adresem domyślnym:

   https://<nazwa-użytkownika>.gitlab.io/<nazwa-repozytorium>
   

2. Podłączenie subdomeny docs.rachuna-net.pl

1. Repozytorium → Settings → Pages → kliknij New Domain

   

2. Ustawienie domeny np. docs.rachuna-net.pl

3. GitLab wygeneruje dwa rekordy DNS:

   • ALIAS:

     docs.rachuna-net.pl.  ALIAS  pl.rachuna-net.gitlab.io.
     

   • TXT:

     _gitlab-pages-verification-code.docs.rachuna-net.pl.  TXT  gitlab-pages-verification-code=<wygenerowany_kod>
     

4. ustawienie rekordów do strefy DNS domeny.

5. GitLab automatycznie zweryfikuje rekordy i wygeneruje certyfikat SSL (Let’s Encrypt)

1. Wystaw swoją aplikacje na gitlab-pages ✅ https://docs-7c5e90.gitlab.io
2. W ustawieniach pages należy wybrać Deploy → page → new domain:

Po wypełnieniu formularza otrzymasz wpisy do rekordów DNS

   docs.rachuna-net.pl ALIAS pl.rachuna-net.gitlab.io.
   _gitlab-pages-verification-code.docs.rachuna-net.pl TXT gitlab-pages-verification-code=XYZ

3. Po chwili następuje aktualizacja domeny
4. Utworzenie Certyfikatu SSL z Let’s Encrypt

3. Podłączenie domeny głównej

Dla domen głównych nie można użyć ALIAS/CNAME, należy użyć rekordu A.

1. W ustawieniach Pages → New Domain → dodaj rachuna-net.pl

2. Skonfiguruj DNS:

   rachuna-net.pl.                                  A     35.185.44.232
   _gitlab-pages-verification-code.rachuna-net.pl.  TXT   gitlab-pages-verification-code=<kod>
   

3. Po propagacji DNS i weryfikacji – certyfikat SSL zostanie wystawiony automatycznie.

4. Efekt końcowy

Po wykonaniu powyższych kroków, strona MkDocs będzie dostępna pod Twoją własną domeną z certyfikatem SSL, np.:

https://docs.rachuna-net.pl

Przydatne linki

• hugo – Dokumentacja
• GitLab Pages – Custom Domains
• Let’s Encrypt

2.3 - Conventional Commits

Format wiadomości commitów

Wiadomość commita powinna być zgodna z poniższym schematem:

<typ>[!][(zakres)]: krótki opis zmiany

Przykłady

feat: dodano obsługę logowania
fix(auth): naprawiono błąd walidacji tokenu
refactor!: przebudowano system autoryzacji (breaking change)
chore(ci): aktualizacja pipeline’a GitLab CI

Typy commitów

Breaking changes

Aby oznaczyć zmianę łamiącą kompatybilność wsteczną, należy dodać wykrzyknik (!) po typie commita.

git commit -m 'refactor!: zmieniono sposób uwierzytelniania'

Korzyści ze stosowania

• ✅ Spójna i czytelna historia commitów
• ✅ Automatyczne generowanie changelogów
• ✅ Wsparcie dla semantic-release i automatycznego wersjonowania
• ✅ Łatwiejsze code review i analiza zmian
• ✅ Możliwość automatycznej walidacji commitów w CI/CD

Podsumowanie

Wdrożenie Conventional Commits to szybki krok w stronę lepszej automatyzacji, przejrzystości i jakości pracy w projektach GitLab. Rekomendujemy uwzględnienie tej konwencji w każdym nowym repozytorium oraz integrację z commitlint, semantic-release i husky.

regexp:

(build|chore|ci|docs|params|feat|fix|perf|refactor|style|test|revert|merge|release|hotfix|fixup|squash|wip|BREAKING CHANGE)(\\(.+\\))?: .+

3 - Infrastructure as a Code

Wstęp do Opentofu

Wdrażając podejście IaC z użyciem OpenTofu, należy przyjąć szereg kluczowych założeń projektowych, które zapewniają bezpieczeństwo, skalowalność oraz powtarzalność środowisk infrastrukturalnych.

Architektura projektu OpenTofu w pl.rachuna-net

# Przykładowy opis struktury projektu
pl.rachuna-net/infrastructure/opentofu
├── gitlab-profile                      # Documentation
├── home.rachuna-net.pl
├── iac-gitlab                          # IaC - Gitlab Management by terraform
├── modules                             # Terraform modules
│   ├── gitlab-group                    # Terraform module for menagment groups
│   ├── gitlab-project                  # Terraform module for menagment projects
│   ├── proxmox-container
│   ├── proxmox-download-container
│   ├── proxmox-vm
│   ├── routeros-bonding
│   ├── routeros-bridge
│   ├── routeros-dhcp-server
│   ├── routeros-dns
│   ├── routeros-ethernet
│   ├── routeros-system
│   ├── routeros-vlan
│   ├── vault-pki-cert-ca
│   └── vault-pki-cert-intermediate
├── proxmox
├── router.rachuna-net.pl
└── vault

Założenia projektów Infrastructure as a Code

Infrastructure as Code (IaC) to podejście do zarządzania infrastrukturą IT, w którym:

• zasoby są definiowane i utrzymywane za pomocą kodu, a nie manualnych operacji.
• automatyczne tworzenie, aktualizowanie oraz usuwanie zasobów w chmurze i środowiskach lokalnych, na podstawie deklaratywnych plików konfiguracyjnych.

Wdrażając podejście IaC z użyciem OpenTofu, należy przyjąć szereg kluczowych założeń projektowych, które zapewniają bezpieczeństwo, skalowalność oraz powtarzalność środowisk infrastrukturalnych.

3.1 - Lista konfiguracji

Lista konfiguracji

Poniżej znajduje się lista projektów Infrastructure as a Code.

project	version	description
iac-gitlab		IAC do zarządzania środowiskiem GitLab.

3.1.1 - IAC-gitlab

IAC do zarządzania środowiskiem GitLab.

3.1.1.1 - Grupy repozytoriów

Tworzenie grupy repozytoriów w GitLab za pomocą OpenTofu

Korzyści wynikające z użycia OpenTofu

OpenTofu pozwala na:

• Automatyzację tworzenia i zarządzania grupami repozytoriów,
• Wersjonowanie konfiguracji, co ułatwia kontrolę zmian,
• Powtarzalność konfiguracji, eliminując błędy manualne.

Definiowanie grupy w OpenTofu

Aby utworzyć grupę repozytoriów w GitLab, należy dodać odpowiednią definicję do pliku konfiguracyjnego OpenTofu.

Przykładowy plik konfiguracyjny OpenTofu

Definicja grupy

📄 Ścieżka pliku: pl.rachuna-net/containers.tf

module "_containers" {
  source = "git@gitlab.com:pl.rachuna-net/infrastructure/opentofu/modules/gitlab-group.git?ref=v1.0.0"

  name           = "containers"
  description    = "Repozytoria z obrazami kontenerowymi."
  parent_group   = local.parent_name
  visibility     = "public"
  default_branch = "main"
  avatar         = "containers"

}

module "containers" {
  source = "./containers/"
}

Definicja parametrów dla dzieci

📄 Ścieżka pliku: pl.rachuna-net/containers/_locals.tf

locals {
  parent_name  = "pl.rachuna-net/containers"
  project_type = "container"
}

data "vault_kv_secret_v2" "github" {
  mount = "kv-devops"
  name  = "github"
}

Weryfikacja planu OpenTofu

Po zapisaniu konfiguracji należy uruchomić polecenie tofu plan, które zwróci listę planowanych zmian:

Wdrożenie zmian

Jeśli planowane zmiany są zgodne z oczekiwaniami, należy wdrożyć je do main poprzez Merge Request (MR), co spowoduje utworzenie grupy repozytoriów w GitLab.

Podsumowanie

Wdrożenie grupy repozytoriów w GitLab za pomocą OpenTofu zapewnia automatyzację, powtarzalność i centralizację zarządzania. Po poprawnym wykonaniu opisanych kroków, nowa grupa repozytoriów będzie gotowa do użytku.

🚀 Gotowe! Grupa repozytoriów została pomyślnie utworzona przy użyciu OpenTofu. 🎉

3.1.1.2 - Repozytorium kodu

Tworzenie repozytorium w GitLab za pomocą OpenTofu

Korzyści wynikające z użycia OpenTofu

OpenTofu pozwala na:

• Automatyzację tworzenia i zarządzania grupami repozytoriów,
• Wersjonowanie konfiguracji, co ułatwia kontrolę zmian,
• Powtarzalność konfiguracji, eliminując błędy manualne.

Definiowanie grupy w OpenTofu

Aby utworzyć repozytorium w GitLab, należy dodać odpowiednią definicję do pliku konfiguracyjnego OpenTofu.

📄 Ścieżka pliku: pl.rachuna-net/containers/opentofu

module "opentofu" {
  source = "git@gitlab.com:pl.rachuna-net/infrastructure/opentofu/modules/gitlab-project.git?ref=v1.0.0"

  name               = "opentofu"
  archived           = false
  description        = "Obraz Dockerowy z narzędziem opentofu."
  visibility         = "public"
  tags               = ["docker", "opentofu"]
  avatar             = "opentofu"
  parent_group       = local.parent_name
  project_type       = "container"
  build_git_strategy = "clone"
  gitlab_ci_path     = "containers/docker.yml@pl.rachuna-net/cicd/gitlab-ci"

  # sonarqube
  is_enabled_sonarqube       = true
  sonarqube_cloud_project_id = "pl.rachuna-net_opentofu"

  # mirror to github
  mirror_url = format(
    "https://%s:%s@github.com/%s/%s.git",
    data.vault_kv_secret_v2.github.data["owner"],
    data.vault_kv_secret_v2.github.data["token"],
    data.vault_kv_secret_v2.github.data["owner"],
    "pl.rachuna-net.containers.opentofu"
  )

  variables = {
    PUBLISH_VAULT_SECRET_PATH = {
      description = "Ścieżka do sekrety Vault, gdzie będą publikowane zmienne środowiskowe",
      value       = "pl.rachuna-net/containers/opentofu:CONTAINER_IMAGE_OPENTOFU"
    }
    PUBLISH_VAULT_VALUE_VARIABLE = {
      description = "Nazwa zmiennej środowiskowej, która będzie publikowana w Vault",
      value       = "CONTAINER_IMAGE_VERSION"
    }
  }
}

Weryfikacja planu OpenTofu

Po zapisaniu konfiguracji należy uruchomić polecenie tofu plan, które zwróci listę planowanych zmian:

Wdrożenie zmian

Jeśli planowane zmiany są zgodne z oczekiwaniami, należy wdrożyć je do main poprzez Merge Request (MR), co spowoduje utworzenie repozytorium w GitLab.

Podsumowanie

Wdrożenie repozytorium w GitLab za pomocą OpenTofu zapewnia automatyzację, powtarzalność i centralizację zarządzania. Po poprawnym wykonaniu opisanych kroków, nowa grupa repozytoriów będzie gotowa do użytku.

🚀 Gotowe! Grupa repozytoriów została pomyślnie utworzona przy użyciu OpenTofu. 🎉

3.2 - OpenTofu Modules

Moduły OpenTofu

Poniżej znajduje lista stworzonych modułów OpenTofu

product	version	Opis
gitlab-group		Zarządzanie grupą w GitLab
gitlab-project		Zarządzanie projektem w GitLab

3.3 - Importowanie obiektów

Importowanie istniejących obiektów

tofu Import – Co to jest i do czego służy?

Do czego służy OpenTofu import?

• Przejmowanie kontroli nad istniejącymi zasobami – jeśli masz już zasoby w chmurze (np. VM w AWS, projekt w GitLab, użytkowników w Azure), możesz je zaimportować do OpenTofu bez ich ponownego tworzenia.
• Unikanie usuwania i ponownego tworzenia zasobów – jeśli ręcznie utworzony zasób nie znajduje się w stanie OpenTofu, ale istnieje, można go dodać do state, zamiast niszczyć i tworzyć od nowa.
• Migracja do OpenTofu – jeśli zarządzałeś zasobami ręcznie lub przy pomocy innego narzędzia (np. Ansible, CloudFormation), możesz je przenieść do OpenTofu.

Przykłady importowanie obiektów

importowanie grupy gitlab

import {
  to = module.pl_rachuna-net.module.infrastructure.module.opentofu.module.group_modules.gitlab_group.group
  id = "100726684"
}

importowanie projektu gitlab

import {
    to = module.pl_rachuna-net.module.infrastructure.module.opentofu.module.modules.module.gitlab_group.gitlab_project.project
    id = "66189322"
}

3.4 - Nadpisanie gitlab states

Wysłanie opentofu state do gitlab

#!/bin/env bash

curl --request POST \
     --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
     --header "Content-Type: application/json" \
     --data-binary "@default.json" \
     "https://gitlab.com/api/v4/projects/${PRROJECT_ID}/terraform/state/${TF_STATE_NAME}"

3.5 - Integracja z projektem gitlab

Integracja z projektem gitlab

Ustawienie terraform state w ustawieniach repozytorium

  terraform init \
  -backend-config="address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}" \
  -backend-config="lock_address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}/lock" \
  -backend-config="unlock_address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}/lock" \
  -backend-config="username=gitlab-ci-token" \
  -backend-config="password=${CI_JOB_TOKEN}" \
  -backend-config="lock_method=POST" \
  -backend-config="unlock_method=DELETE" \
  -backend-config="retry_wait_min=5"

dla OpenTofu

  tofu init \
  -backend-config="address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}" \
  -backend-config="lock_address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}/lock" \
  -backend-config="unlock_address=${CI_SERVER_URL}/api/v4/projects/${CI_PROJECT_ID}/terraform/state/${TF_STATE_NAME}/lock" \
  -backend-config="username=gitlab-ci-token" \
  -backend-config="password=${CI_JOB_TOKEN}" \
  -backend-config="lock_method=POST" \
  -backend-config="unlock_method=DELETE" \
  -backend-config="retry_wait_min=5"

gdzie:

• CI_PROJECT_ID - id projektu w gitlab
• CI_SERVER_URL - serwer URL
• TF_STATE_NAME - nazwa instancji state

Terraform state z procesu CI¹

4 - Concepts

For many projects, users may not need much information beyond the information in the Overview, so this section is optional. However if there are areas where your users will need a more detailed understanding of a given term or feature in order to do anything useful with your project (or to not make mistakes when using it) put that information in this section. For example, you may want to add some conceptual pages if you have a large project with many components and a complex architecture.

Remember to focus on what the user needs to know, not just what you think is interesting about your project! If they don’t need to understand your original design decisions to use or contribute to the project, don’t put them in, or include your design docs in your repo and link to them. Similarly, most users will probably need to know more about how features work when in use rather than how they are implemented. Consider a separate architecture page for more detailed implementation and system design information that potential project contributors can consult.

5 - Core Tasks

Think about your project’s features and use cases. Use these to choose your core tasks. Each granular use case (enable x, configure y) should have a corresponding tasks page or tasks page section. Users should be able to quickly refer to your core tasks when they need to find out how to do one specific thing, rather than having to look for the instructions in a bigger tutorial or example. Think of your tasks pages as a cookbook with different procedures your users can combine to create something more substantial.

You can give each task a page, or you can group related tasks together in a page, such as tasks related to a particular feature. As well as grouping related tasks in single pages, you can also group task pages in nested folders with an index page as an overview, as seen in this example site. Or if you have a small docset like the Docsy User Guide with no Tutorials or Concepts pages, consider adding your feature-specific pages at the top level of your docs rather than in a Tasks section.

Each task should give the user

• The prerequisites for this task, if any (this can be specified at the top of a multi-task page if they’re the same for all the page’s tasks. “All these tasks assume that you understand….and that you have already….”).
• What this task accomplishes.
• Instructions for the task. If it involves editing a file, running a command, or writing code, provide code-formatted example snippets to show the user what to do! If there are multiple steps, provide them as a numbered list.
• If appropriate, links to related concept, tutorial, or example pages.

5.1 - Bed and Chair Metrics

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

5.2 - Porridge Assessment

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

5.3 - Another Task

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

5.4 - Working with Ponycopters

This is the section landing page.

5.4.1 - Configuring Ponycopters

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

5.4.2 - Launching Ponycopters

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

6 - Tutorials

Tutorials are complete worked examples made up of multiple tasks that guide the user through a relatively simple but realistic scenario: building an application that uses some of your project’s features, for example. If you have already created some Examples for your project you can base Tutorials on them. This section is optional. However, remember that although you may not need this section at first, having tutorials can be useful to help your users engage with your example code, especially if there are aspects that need more explanation than you can easily provide in code comments.

6.1 - Multi-Bear Domicile Setup

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

6.2 - Another Tutorial

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

Add some sections here to see how the ToC looks like. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

This Document

Inguina genus: Anaphen post: lingua violente voce suae meus aetate diversi. Orbis unam nec flammaeque status deam Silenum erat et a ferrea. Excitus rigidum ait: vestro et Herculis convicia: nitidae deseruit coniuge Proteaque adiciam eripitur? Sitim noceat signa probat quidem. Sua longis fugatis quidem genae.

Pixel Count

Tilde photo booth wayfarers cliche lomo intelligentsia man braid kombucha vaporware farm-to-table mixtape portland. PBR&B pickled cornhole ugh try-hard ethical subway tile. Fixie paleo intelligentsia pabst. Ennui waistcoat vinyl gochujang. Poutine salvia authentic affogato, chambray lumbersexual shabby chic.

Contact Info

Plaid hell of cred microdosing, succulents tilde pour-over. Offal shabby chic 3 wolf moon blue bottle raw denim normcore poutine pork belly.

External Links

Stumptown PBR&B keytar plaid street art, forage XOXO pitchfork selvage affogato green juice listicle pickled everyday carry hashtag. Organic sustainable letterpress sartorial scenester intelligentsia swag bushwick. Put a bird on it stumptown neutra locavore. IPhone typewriter messenger bag narwhal. Ennui cold-pressed seitan flannel keytar, single-origin coffee adaptogen occupy yuccie williamsburg chillwave shoreditch forage waistcoat.

This is the final element on the page and there should be no margin below this.

7 - Reference

If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen, Javadoc, or other doc generation tools by putting them in your static/ directory. Find out more in Adding static content. For OpenAPI reference, Docsy also provides a Swagger UI layout and shortcode that renders Swagger UI using any OpenAPI YAML or JSON file as source.

7.1 - Parameter Reference

Text can be bold, italic, or strikethrough. Links should be blue with no underlines (unless hovered over).

There should be whitespace between paragraphs. Vape migas chillwave sriracha poutine try-hard distillery. Tattooed shabby chic small batch, pabst art party heirloom letterpress air plant pop-up. Sustainable chia skateboard art party banjo cardigan normcore affogato vexillologist quinoa meggings man bun master cleanse shoreditch readymade. Yuccie prism four dollar toast tbh cardigan iPhone, tumblr listicle live-edge VHS. Pug lyft normcore hot chicken biodiesel, actually keffiyeh thundercats photo booth pour-over twee fam food truck microdosing banh mi. Vice activated charcoal raclette unicorn live-edge post-ironic. Heirloom vexillologist coloring book, beard deep v letterpress echo park humblebrag tilde.

90’s four loko seitan photo booth gochujang freegan tumeric listicle fam ugh humblebrag. Bespoke leggings gastropub, biodiesel brunch pug fashion axe meh swag art party neutra deep v chia. Enamel pin fanny pack knausgaard tofu, artisan cronut hammock meditation occupy master cleanse chartreuse lumbersexual. Kombucha kogi viral truffaut synth distillery single-origin coffee ugh slow-carb marfa selfies. Pitchfork schlitz semiotics fanny pack, ugh artisan vegan vaporware hexagon. Polaroid fixie post-ironic venmo wolf ramps kale chips.

There should be no margin above this first sentence.

Blockquotes should be a lighter gray with a border along the left side in the secondary color.

There should be no margin below this final sentence.

First Header 2

This is a normal paragraph following a header. Knausgaard kale chips snackwave microdosing cronut copper mug swag synth bitters letterpress glossier craft beer. Mumblecore bushwick authentic gochujang vegan chambray meditation jean shorts irony. Viral farm-to-table kale chips, pork belly palo santo distillery activated charcoal aesthetic jianbing air plant woke lomo VHS organic. Tattooed locavore succulents heirloom, small batch sriracha echo park DIY af. Shaman you probably haven’t heard of them copper mug, crucifix green juice vape single-origin coffee brunch actually. Mustache etsy vexillologist raclette authentic fam. Tousled beard humblebrag asymmetrical. I love turkey, I love my job, I love my friends, I love Chardonnay!

Deae legum paulatimque terra, non vos mutata tacet: dic. Vocant docuique me plumas fila quin afuerunt copia haec o neque.

On big screens, paragraphs and headings should not take up the full container width, but we want tables, code blocks and similar to take the full width.

Scenester tumeric pickled, authentic crucifix post-ironic fam freegan VHS pork belly 8-bit yuccie PBR&B. I love this life we live in.

Second Header 2

This is a blockquote following a header. Bacon ipsum dolor sit amet t-bone doner shank drumstick, pork belly porchetta chuck sausage brisket ham hock rump pig. Chuck kielbasa leberkas, pork bresaola ham hock filet mignon cow shoulder short ribs biltong.

Header 3

This is a code block following a header.

Next level leggings before they sold out, PBR&B church-key shaman echo park. Kale chips occupy godard whatever pop-up freegan pork belly selfies. Gastropub Belinda subway tile woke post-ironic seitan. Shabby chic man bun semiotics vape, chia messenger bag plaid cardigan.

Header 4

• This is an unordered list following a header.
• This is an unordered list following a header.
• This is an unordered list following a header.

Header 5

1. This is an ordered list following a header.
2. This is an ordered list following a header.
3. This is an ordered list following a header.

Header 6

There’s a horizontal rule above and below this.

Here is an unordered list:

• Liverpool F.C.
• Chelsea F.C.
• Manchester United F.C.

And an ordered list:

1. Michael Brecker
2. Seamus Blake
3. Branford Marsalis

And an unordered task list:

• Create a Hugo theme
• Add task lists to it
• Take a vacation

And a “mixed” task list:

• Pack bags
• ?
• Travel!

And a nested list:

• Jackson 5
  • Michael
  • Tito
  • Jackie
  • Marlon
  • Jermaine
• TMNT
  • Leonardo
  • Michelangelo
  • Donatello
  • Raphael

Definition lists can be used with Markdown syntax. Definition headers are bold.

Name

Godzilla

Born

1952

Birthplace

Japan

Color

Green

Tables should have bold headings and alternating shaded rows.

If a table is too wide, it should scroll horizontally.

Code snippets like var foo = "bar"; can be shown inline.

Also, this should vertically align with this and this.

Code can also be shown in a block element.

foo := "bar";
bar := "foo";

Code can also use syntax highlighting.

func main() {
  input := `var foo = "bar";`

  lexer := lexers.Get("javascript")
  iterator, _ := lexer.Tokenise(nil, input)
  style := styles.Get("github")
  formatter := html.New(html.WithLineNumbers())

  var buff bytes.Buffer
  formatter.Format(&buff, style, iterator)

  fmt.Println(buff.String())
}

Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.

Inline code inside table cells should still be distinguishable.

Small images should be shown at their actual size.

Large images should always scale down and fit in the content container.

The photo above of the Spruce Picea abies shoot with foliage buds: Bjørn Erik Pedersen, CC-BY-SA.

Components

Alerts

Another Heading

8 - Contribution Guidelines

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Netlify to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Quick start with Netlify

Here’s a quick guide to updating the docs. It assumes you’re familiar with the GitHub workflow and you’re happy to use the automated preview of your doc updates:

1. Fork the Goldydocs repo on GitHub.
2. Make your changes and send a pull request (PR).
3. If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
4. Wait for the automated PR workflow to do some checks. When it’s ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
5. Click Details to the right of “Deploy preview ready” to see a preview of your updates.
6. Continue updating your doc and pushing your changes until you’re happy with the content.
7. When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

1. Click Edit this page in the top right hand corner of the page.
2. If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
3. Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

1. Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.146.0 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.

2. Fork the Goldydocs repo repo into your own project, then create a local copy using git clone.

   git clone --branch v0.12.0 --depth 1 https://github.com/google/docsy-example.git
   

3. Run hugo server in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.

4. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

• Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
• Hugo documentation: Comprehensive reference for Hugo.
• Github Hello World!: A basic introduction to GitHub concepts and workflow.

9 - Examples

Do you have any example applications or code for your users in your repo or elsewhere? Link to your examples here.