Create a single source of documentation for the trento project

.gitignore

@@ -1 +1,5 @@
 .elixir_ls
+.env
+antora_public
+node_modules
+antora_tmp

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2024 SUSE LLC
+Copyright 2025 SUSE LLC
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -1,8 +1,45 @@
 # Trento docs
 
-This repository contains the Trento project documentation that does not interest a specific service, such as ADR, coding standards and best practices, CI workflows, and templates.
+This repository is the source of truth for the Trento project documentation. 
 
-- [Coding standards](./coding-standards)
-- [Architecture Decision Records (ADR)](./adr)
+- [Trento components documentation](./components/)
+- [Developer Documentation](./developer/)
 - [Templates](./templates)
-- [Guides](./guides)
+
+> **Note:** The content of user facing documentation is fetched from https://github.com/SUSE/doc-unversioned/tree/main/trento
+
+## How to contribute to development documentation? 
+
+  1. **Create new documentation in `.adoc`**.
+
+  2. **Choose the appropriate location** for your new `.adoc` file:
+   - For **developer documentation**,like adr, rfc or architecture use `deveveloper/`.
+   - For **component-specific docs**, like web, wanda or the agent, use `components/<component-name>/`.
+
+  3. **Add new documentation to trento-docs site by enriching the Antora collector**
+   The content of the modules directory is responsible for the build of the documentation page.
+
+   Open the appropriate `nav.adoc` file under `modules/<module>/nav.adoc` and add a new entry for your page, for example:
+   ```adoc
+   * xref:my-new-page.adoc[My New Page]
+   ```
+   Make sure the file path is relative to modules/<module>/pages
+
+  4. Install Dependency
+
+  ```bash
+  npm i -D -E antora
+  ```
+
+  5. Build Antora page
+
+  ```bash
+  npx antora --fetch antora-playbook.yml
+  ```
+
+  6. Run page
+
+ ```bash
+ xdg-open antora_public/index.html
+ ```
+

antora-playbook.yml

@@ -0,0 +1,26 @@
+site:
+  title: Trento Documentation
+  url: https://trento-project.github.io
+  start_page: docs::index.adoc
+
+content:
+  sources:
+    - url: .
+      branches:
+        - HEAD
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+
+output:
+  dir: ./antora_public
+
+antora:
+  extensions:
+  - '@antora/collector-extension'
+  - require: '@antora/lunr-extension'
+    index_latest_only: true
+
+
+

antora.yml

@@ -0,0 +1,66 @@
+name: docs
+title: Trento Documentation
+version: ~
+nav:
+- modules/trento_doc_unversioned/nav.adoc
+- modules/components/nav.adoc
+- modules/api/nav.adoc
+- modules/developer/nav.adoc
+
+ext:
+  collector:
+    # Fetch trento official documentation
+    - run:
+        command: git clone https://github.com/SUSE/doc-unversioned temp-doc-unversioned
+    # Get content from doc-unversioned
+    - scan:
+        dir: temp-doc-unversioned/trento/adoc
+        files: '**/*.adoc'
+        into: modules/trento_doc_unversioned/pages
+    # Get images from doc-unversioned
+    - scan:
+        dir: temp-doc-unversioned/trento/images/src/png
+        files: '**/*.png'
+        into: modules/trento_doc_unversioned/images
+    # Build asciidoc attributes from doc-unversioned
+    - run:
+        command: ./scripts/generate-attributes-yaml.sh temp-doc-unversioned/trento/adoc/generic-attributes.adoc ./antora_tmp/antora.yml
+    # Scan generated antora file to merge the asciidoc attributes
+    - scan:
+        dir: antora_tmp
+        files: 'antora.yml'
+    # Clean fetched doc-unversioned and remove generated antora file
+    - clean:
+        dir: temp-doc-unversioned
+    - clean:
+        dir: antora_tmp
+
+# Trento upstream projects components
+    - clean:
+        dir: modules/components/pages
+    - clean:
+        dir: modules/components/images
+    - scan:
+        dir:  components/
+        files: '**/*.adoc'
+        into: modules/components/pages
+    - scan:
+        dir: components/assets
+        files: '**/*.{png,jpg,jpeg,svg,gif}'
+        into: modules/components/images
+# Trento developer documentation
+    - clean:
+        dir: modules/developer/pages
+    - scan:
+        dir: developer/
+        files: '**/*.adoc'
+        into: modules/developer/pages
+# Images developer documentation
+    - clean:
+        dir: modules/developer/images
+    - scan:
+        dir: developer/assets
+        files: '**/*.{png,jpg,jpeg,svg,gif}'
+        into: modules/developer/images
+
+

components/agent/ci-cd-variables.adoc

@@ -0,0 +1,16 @@
+== CI/CD Variables expected by Trento GH Action Runner
+
+These are a list of the variables that our GitHub Workflow supports in
+order to make a `+trento+` deployment.
+
+=== Secrets
+
+==== `+OBS_USER+`
+
+This the OBS user that will trigger build in `+opensuse.build.org+`
+`+obsuser+`
+
+==== `+OBS_PASS+`
+
+This is the password for the OBS user that will trigger build in
+`+opensuse.build.org+` `+obspassword+`

components/agent/development/how-to-make-a-release.adoc

@@ -0,0 +1,80 @@
+== How to release a new version of Trento Agent
+
+____
+Note: this document is a draft!
+____
+
+=== Pre-requisites
+
+Install
+https://github.com/github-changelog-generator/github-changelog-generator[github-changelog-generator]
+globally in your dev box:
+
+....
+gem install github_changelog_generator
+....
+
+=== Update the changelog and create a new tag
+
+The automatic changelog generation leverages GitHub labels very heavily
+to produce a meaningful output following the
+https://keepachangelog.com/en/1.0.0/[Keep a Changelog] specification,
+grouping pull requests and issues in sections.
+
+Use the labels as follows: - `+enhancement+` or `+addition+` items go in
+the `+Added+` section; - `+bug+` or `+fix+` items go in the `+Fixed+`
+section; - `+removal+` items go in the `+Removed+` section; - unlabelled
+pull requests go in the `+Other Changes+` section; - unlabelled closed
+issues are ignored.
+
+You don’t have to label everything: the intent of the changelog is to
+communicate highlights to end-users, while also being comprehensive;
+this is why the `+Other changes+` section catches all the unlabelled
+items and is rendered last.
+
+Once you do a quick round of issues/PR triaging to apply labels in a
+meaningful way, follow these steps:
+
+[source,bash]
+----
+# always create a dedicated release branch
+git switch -c release-x.y.z
+
+# x1.y1.z1 is the previous release tag
+github_changelog_generator --since-tag=x1.y1.z1 --future-release=x.y.z
+
+git add CHANGELOG.md
+git commit -m "add x.y.z changelog entry"
+
+# maybe make some other last minute changes
+# [...]
+
+# merge and tag, making sure the tag is on the merge commit
+git switch main
+git merge --no-ff release-x.y.z
+git tag x.y.z
+
+# don't forget to force update the rolling tag!
+git fetch --tags -f
+
+# push directly
+git push --tags origin main
+----
+
+Optionally, open a pull request from the release branch instead of
+tagging and pushing manually.
+
+=== GitHub release
+
+____
+Note: this step will soon be automated.
+____
+
+Go to the https://github.com/trento-project/agent/releases[project
+releases page] and create a new release, then:
+
+* use the just created git tag as the release tag and title;
+* copy-paste the last changelog entry from `+CHANGELOG.md+` as the
+release body;
+* hit the green button;
+* profit!

components/helm_charts/trento-server.adoc

@@ -0,0 +1,135 @@
+== Trento Server Helm Chart
+
+=== Installation
+
+==== Requirements
+
+The _Trento Server_ is intended to run in many ways, depending on users’
+already existing infrastructure, but it’s designed to be cloud-native
+and OS agnostic. As such, our default installation method provisions a
+minimal, single node, [K3S] Kubernetes cluster to run its various
+components in Linux containers. The suggested physical resources for
+running all the _Trento Server_ components are 2GB of RAM and 2 CPU
+cores. The _Trento Server_ needs to reach the target infrastructure.
+
+==== Quick-start installation
+
+An installation script is provided to quickly get you started by
+automatically provisioning, installing and updating the latest version
+of Trento.
+
+The script installs a single node K3s cluster and uses the
+link:../charts/trento-server[trento-server Helm chart] to bootstrap a
+complete Trento server component.
+
+You can `+curl | bash+` if you want to live on the edge.
+
+....
+curl -sfL https://raw.githubusercontent.com/trento-project/helm-charts/main/scripts/install-server.sh | bash
+....
+
+Or you can fetch the script, and then execute it manually.
+
+....
+curl -O https://raw.githubusercontent.com/trento-project/helm-charts/main/scripts/install-server.sh
+chmod 700 install-server.sh
+sudo ./install-server.sh
+....
+
+_Note: if a Trento server is already installed in the host, it will be
+updated._
+
+Please refer to the link:#helm-chart[Helm chart] section for more
+information about the Helm chart.
+
+==== Manual installation
+
+===== Helm chart
+
+The charts/trento-server directory contains the Helm chart for
+installing Trento Server in a Kubernetes cluster.
+
+===== Install K3S
+
+If installing as root:
+
+....
+# curl -sfL https://get.k3s.io | sh
+....
+
+If installing as non-root user:
+
+....
+curl -sfL https://get.k3s.io | sh -s - --write-kubeconfig-mode 644
+....
+
+Export KUBECONFIG env variable:
+
+....
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+....
+
+Please refer to the
+https://rancher.com/docs/k3s/latest/en/installation/[K3S official
+documentation] for more information about the installation.
+
+===== Install Helm and chart dependencies
+
+Install Helm:
+
+....
+curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash
+....
+
+Please refer to the https://helm.sh/docs/intro/install/[Helm official
+documentation] for more information about the installation.
+
+===== Install Trento Server
+
+Add third-party Helm repositories:
+
+....
+helm repo add bitnami https://charts.bitnami.com/bitnami
+helm repo update
+....
+
+Install chart dependencies:
+
+....
+cd charts/trento-server/
+helm dependency update
+....
+
+Install the Trento Server chart:
+
+....
+helm install trento .
+....
+
+or perform a rolling update:
+
+....
+helm upgrade trento . --set trento-web.trentoWebOrigin="trento.example.com"
+....
+
+_Note: be sure to replace trento.example.com with a valid hostname that
+points to the Trento server._
+
+Now you can connect to the web server via `+http://localhost+` and point
+the agents to the cluster IP address.
+
+===== Other Helm chart usage examples
+
+Use a different container image (e.g. the `+rolling+` one):
+
+....
+helm install trento . --set trento-web.image.tag="rolling" --set trento-wanda.image.tag="rolling"
+....
+
+Use a different container registry:
+
+....
+helm install trento . --set trento-web.image.repository="ghcr.io/myrepo/trento-web" --set trento-wanda.image.repository="ghcr.io/myrepo/trento-wanda"
+....
+
+Please refer to the the subcharts `+values.yaml+` for an advanced usage.