feat(doc): Enhancement, cleanup, add package instructions

- remove trailing spaces - add instruction for packages - reindent YAML examples - remove section telling that there is no config files, as `katenary.yaml` file can now be used
2025-08-29 13:24:32 +02:00
parent 6c2e8fa9b2
commit 6cd1c92997
9 changed files with 297 additions and 261 deletions
--- a/doc/share/man/man1/katenary.1
+++ b/doc/share/man/man1/katenary.1
@@ -1,7 +1,7 @@
 '\" t
 .\" Automatically generated by Pandoc 3.1.11.1
 .\"
-.TH "Katenary" "1" "2025-08-21" "mkdocs-manpage v2.0.1" "Katenary helm chart generator"
+.TH "Katenary" "1" "2025-08-29" "mkdocs-manpage v2.0.1" "Katenary helm chart generator"
 .SH Basic Usage
 Basically, you can use \f[CR]katenary\f[R] to transpose a docker\-compose file (or any compose file compatible with \f[CR]podman\-compose\f[R] and \f[CR]docker\-compose\f[R]) to a configurable Helm Chart.
 This resulting helm chart can be installed with \f[CR]helm\f[R] command to your Kubernetes cluster.
@@ -38,18 +38,18 @@ With \[dq]labels\[dq], you should do:
 .EX
 # in compose file
 services:
-    webapp:
-        image: php:7\-apache
-        ports:
-            \- 8080:80
-        environment:
-            DB_HOST: database
-        labels:
-        katenary.v3/ingress: |\-
-            hostname: myapp.example.com
-            port: 8080
-        katenary.v3/map\-env: |\-
-            DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
+  webapp:
+    image: php:7\-apache
+    ports:
+      \- 8080:80
+    environment:
+      DB_HOST: database
+    labels:
+    katenary.v3/ingress: |\-
+      hostname: myapp.example.com
+      port: 8080
+    katenary.v3/map\-env: |\-
+      DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
 .EE
 .PP
 Using a Katenary file, you can do:
@@ -57,21 +57,21 @@ Using a Katenary file, you can do:
 .EX
 # in compose file, no need to add labels
 services:
-    webapp:
-        image: php:7\-apache
-        ports:
-            \- 8080:80
-        environment:
-            DB_HOST: database
+  webapp:
+    image: php:7\-apache
+    ports:
+      \- 8080:80
+    environment:
+      DB_HOST: database

 # in katenary.yaml
 webapp:
-    ingress:
-        hostname: myapp.example.com
-        port: 8080
+  ingress:
+    hostname: myapp.example.com
+    port: 8080

-    map\-env:
-        DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
+  map\-env:
+    DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
 .EE
 .PP
 YAML in multiline label
@@ -162,15 +162,15 @@ See this compose file:
 version: \[dq]3\[dq]

 services:
-    webapp:
-        image: php:8\-apache
-        depends_on:
-            \- database
+  webapp:
+    image: php:8\-apache
+    depends_on:
+      \- database

-    database:
-        image: mariadb
-        environment:
-            MYSQL_ROOT_PASSWORD: foobar
+  database:
+    image: mariadb
+    environment:
+      MYSQL_ROOT_PASSWORD: foobar
 .EE
 .PP
 In this case, \f[CR]webapp\f[R] needs to know the \f[CR]database\f[R] port because the \f[CR]depends_on\f[R] points on it and Kubernetes has not (yet) solution to check the database startup.
@@ -181,18 +181,18 @@ So, instead of exposing the port in the compose definition, let\[aq]s declare th
 version: \[dq]3\[dq]

 services:
-    webapp:
-        image: php:8\-apache
-        depends_on:
-            \- database
+  webapp:
+    image: php:8\-apache
+    depends_on:
+      \- database

-    database:
-        image: mariadb
-        environment:
-            MYSQL_ROOT_PASSWORD: foobar
-        labels:
-            katenary.v3/ports: |\-
-                \- 3306
+  database:
+    image: mariadb
+    environment:
+      MYSQL_ROOT_PASSWORD: foobar
+    labels:
+      katenary.v3/ports: |\-
+        \- 3306
 .EE
 .SS Declare ingresses
 It\[aq]s very common to have an Ingress resource on web application to deploy on Kubernetes.
@@ -203,14 +203,14 @@ You just need to declare the hostname and the port to bind.
 .IP
 .EX
 services:
-    webapp:
-        image: ...
-        ports: 8080:5050
-        labels:
-            katenary.v3/ingress: |\-
-                # the target port is 5050 wich is the \[dq]service\[dq] port
-                port: 5050
-                hostname: myapp.example.com
+  webapp:
+    image: ...
+    ports: 8080:5050
+    labels:
+      katenary.v3/ingress: |\-
+        # the target port is 5050 wich is the \[dq]service\[dq] port
+        port: 5050
+        hostname: myapp.example.com
 .EE
 .PP
 Note that the port to bind is the one used by the container, not the used locally.
@@ -223,29 +223,29 @@ With a compose file, there is no problem as Docker/Podman allows resolving the n
 .IP
 .EX
 services:
-    webapp:
-        image: php:7\-apache
-        environment:
-            DB_HOST: database
+  webapp:
+    image: php:7\-apache
+    environment:
+      DB_HOST: database

-    database:
-        image: mariadb
+  database:
+    image: mariadb
 .EE
 .PP
 Katenary prefixes the services with \f[CR]{{ .Release.Name }}\f[R] (to make it possible to install the application several times in a namespace), so you need to \[dq]remap\[dq] the environment variable to the right one.
 .IP
 .EX
 services:
-    webapp:
-        image: php:7\-apache
-        environment:
-            DB_HOST: database
-        labels:
-            katenary.v3/mapenv: |\-
-                DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]
+  webapp:
+    image: php:7\-apache
+    environment:
+      DB_HOST: database
+    labels:
+      katenary.v3/mapenv: |\-
+        DB_HOST: \[dq]{{ .Release.Name }}\-database\[dq]

-    database:
-        image: mariadb
+  database:
+    image: mariadb
 .EE
 .PP
 This label can be used to map others environment for any others reason.
@@ -254,13 +254,13 @@ to change an informational environment variable.
 .IP
 .EX
 services:
-    webapp:
-        #...
-        environment:
-            RUNNING: docker
-        labels:
-            katenary.v3/mapenv: |\-
-                RUNNING: kubernetes
+  webapp:
+    #...
+    environment:
+      RUNNING: docker
+    labels:
+      katenary.v3/mapenv: |\-
+        RUNNING: kubernetes
 .EE
 .PP
 In the above example, \f[CR]RUNNING\f[R] will be set to \f[CR]kubernetes\f[R] when you\[aq]ll deploy the application with helm, and it\[aq]s \f[CR]docker\f[R] for \[dq]Podman\[dq] and \[dq]Docker\[dq] executions.
@@ -271,9 +271,9 @@ While compose labels are string, we can use \f[I]here\-doc\f[R] syntax using \f[
 .IP
 .EX
 label\-name: |\-
-    # this is actually a multiline string here
-    key1: value1
-    key2: value2
+  # this is actually a multiline string here
+  key1: value1
+  key2: value2
 .EE
 .PP
 Katenary will try to \f[I]Unmarshal\f[R] these labels.
@@ -445,9 +445,9 @@ The label value is a YAML object with the following attributes: \- command: the
 .IP
 .EX
 labels:
-    katenary.v3/cronjob: |\-
-        command: echo \[dq]hello world\[dq]
-        schedule: \[dq]* */1 * * *\[dq] # or \[at]hourly for example
+  katenary.v3/cronjob: |\-
+    command: echo \[dq]hello world\[dq]
+    schedule: \[dq]* */1 * * *\[dq] # or \[at]hourly for example
 .EE
 .SS katenary.v3/dependencies
 Add Helm dependencies to the service.
@@ -527,7 +527,7 @@ It adds environment variables from another service to the current service.
 service1:
  image: nginx:1.19
  environment:
-      FOO: bar
+    FOO: bar

 service2:
  image: php:7.4\-fpm
@@ -535,7 +535,7 @@ service2:
    # get the congigMap from service1 where FOO is 
    # defined inside this service too
    katenary.v3/env\-from: |\-
-        \- myservice1
+      \- myservice1
 .EE
 .SS katenary.v3/exchange\-volumes
 Add exchange volumes (empty directory on the node) to share data