Better doc for ReadTheDocs

doc/docs/usage.md

@@ -15,7 +15,9 @@ Katenary transforms compose services this way:
 
 Katenary can also configure containers grouping in pods, declare dependencies, ignore some services, force variables as secrets, mount files as `configMap`, and many others things. To adapt the helm chart generation, you will need to use some specific labels.
 
-## Try to convert
+For more complete label usage, see [the labels page](/labels).
+
+## Make convertion
 
 After having installed `katenary`, the standard usage is to call:
 
@@ -25,13 +27,25 @@ katenary convert
 
 It will search standard compose files in the current directory and try to create a helm chart in "chart" directory.
 
-Katenary respects the Docker rules for overrides files, and you can of course force others files:
+!!! Info
+    Katenary uses the compose-go library which respects the Docker and Docker-Compose specification. Keep in mind that it will find files exactly the same way as `docker-compose` and `podman-compose` do it.
+
+
+Of course, you can provide others files than the default with (cummulative) `-c` options:
+
 ```bash
 katenary convert -c file1.yaml -c file2.yaml
 ```
 
+## Some common labels to use
 
-## Work with Depends On?
+Katenary proposes a lot of labels to configure the helm chart generation, but some are very important.
+
+!!! Info
+    For more complete label usage, see [the labels page](/labels).
+
+
+### Work with Depends On?
 
 Kubernetes does not propose service or pod starting detection from others pods. But katenary will create init containers to make you able to wait for a service to respond. But you'll probably need to adapt a bit the compose file.
 
@@ -72,3 +86,72 @@ services:
             katenary.io/ports: 3306
 ```
 
+### Declare ingresses
+
+It's very common to have an `Ingress` on web application to deploy on Kuberenetes. The `katenary.io/ingress` declare the port to bind.
+
+```yaml
+# ...
+services:
+    webapp:
+        image: ...
+        ports: 8080:5050
+        labels:
+            katenary.io/ingress: 5050
+```
+
+Note that the port to bind is the one used by the container, not the used locally. This is because Katenary create a service to bind the container itself.
+
+
+### Map environment to helm values
+
+A lot of framework needs to receive service host or IP in an environment variable to configure the connexion. For example, to connect a PHP application to a database.
+
+With a compose file, there is no problem as Docker/Podman allows to resolve the name by container name:
+
+```yaml
+services:
+    webapp:
+        image: php:7-apache
+        environment:
+            DB_HOST: database
+
+    database:
+        image: mariadb
+```
+
+Katenary prefixes the services with `{{ .Release.Name }}` (to make it possible to install the application several times in a namespace), so you need to "remap" the environment variable to the right one.
+
+
+```yaml
+services:
+    webapp:
+        image: php:7-apache
+        environment:
+            DB_HOST: database
+        labels:
+            katenary.io/mapenv: |
+                DB_HOST: "{{ .Release.Name }}-database"
+
+    database:
+        image: mariadb
+```
+
+!!! Warning
+    This is a "multiline" label that accepts YAML or JSON content, don't forget to add a pipe char (`|`) and to indent your content
+
+This label can be used to map others environment for any others reason. E.g. to change an informational environment variable.
+
+```yaml
+
+services:
+    webapp:
+        #...
+        environment:
+            RUNNING: docker
+        labels:
+            katenary.io/mapenv: |
+                RUNNING: kubernetes
+```
+
+In the above example, `RUNNING` will be set to `kubernetes` when you'll deploy the application with helm, and it's `docker` for "podman" and "docker" executions.