Add doc (WIP)

doc/docs/index.md

@@ -0,0 +1,47 @@
+# Home
+
+Welcome to the documentation of Katenary.
+
+## What is Katenary?
+
+Katenary is a project that aims to help you to transform "compose" files (`docker-compose.yml`, `podman-compose.yml`...) to a complete and production ready [Helm Chart](https://helm.sh).
+
+It uses your current file and optionnaly labels to configure the result.
+
+It's an opensource project, under MIT licence, partially developped at [Smile](https://smile.eu). The project source code is hosted on the [Katenary GitHub Repository](https://github.com/metal3d/katenary).
+
+## Install Katenary
+
+Katenary is developped in [Go](https://go.dev). The binary is statically linked, so you can only download it from the [release page](https://github.com/metal3d/katenary/releases) of the project in GutHub.
+
+You need to select the right binary for your operating system and architecture, and copy the binary in a directory that is in your `PATH`.
+
+If you are a Linux user, you can use the "one line installation command" which will download the binary in you `$HOME/.local/bin` directory if it exists.
+
+```bash
+sh <(curl -sSL https://raw.githubusercontent.com/metal3d/katenary/master/install.sh)
+```
+
+You can also build and install it yourself, the giver Makefile provides a `build` command that uses `podman` or `docker` to build the binary. You don't need to install Go compiler so.
+
+```bash
+git clone https://github.com/metal3d/katenary.git
+cd katenary
+make build
+```
+
+Then, copy `./katenary` binary to you `PATH` (`~/.local/bin` or `/usr/local/bin` with `sudo`) and type `katenary version` and / or `katenary help`
+
+## Install completion
+
+Katenary uses the very nice project named `cobra` to manage flags, argument and auto-completion.
+
+You can activate it with:
+```bash
+# replace "bash" by "zsh" if needed
+source <(katenary completion bash)
+```
+
+Add this line in you `~/.profile` or `~/.bashrc` file to have completion at startup.
+
+

doc/docs/statics/addons.js

@@ -0,0 +1,41 @@
+function addSmileLogo() {
+  let logo = document.createElement("img");
+  logo.src = "/statics/Logo_Smile.png";
+  logo.classList.add("smile-logo");
+  logo.alt = "Smile logo";
+
+  let link = document.createElement("a");
+  link.href = "https://www.smile.eu";
+  link.target = "_blank";
+  link.title = "Smile website";
+
+  link.appendChild(logo);
+
+  logo.addEventListener("load", () => {
+    let side = document.querySelector(".wy-menu");
+    side.appendChild(link);
+  });
+}
+
+function addKatenaryLogo() {
+  let logo = document.createElement("img");
+  logo.src = "/statics/logo.png";
+  logo.classList.add("logo");
+  logo.alt = "Katenary logo";
+
+  let link = document.createElement("a");
+  link.href = "/";
+  link.title = "Index page";
+
+  link.appendChild(logo);
+
+  logo.addEventListener("load", () => {
+    let side = document.querySelector(".wy-nav-side");
+    side.insertBefore(link, side.firstChild);
+  });
+}
+
+document.addEventListener("DOMContentLoaded", () => {
+  addKatenaryLogo();
+  addSmileLogo();
+});

doc/docs/statics/main.css

@@ -0,0 +1,19 @@
+.wy-nav-side {
+  background-color: #333333;
+}
+.wy-nav-side img.logo {
+  width: 50%;
+  margin-left: 25%;
+  text-align: center;
+}
+
+.wy-side-nav-search {
+  margin-top: 1em;
+  background-color: #555555;
+}
+
+.smile-logo {
+  width: 80%;
+  margin-top: 2em;
+  margin-left: 10%;
+}

doc/docs/usage.md

@@ -0,0 +1,74 @@
+# Basic Usage
+
+Basically, you can use `katenary` to transpose a docker-compose file (or any compose file compatible with `podman-compose` and `docker-compose`) to a configurable Helm Chart. This resulting helm chart can be installed with `helm` command to your Kubernetes cluster.
+
+Katenary transforms compose services this way:
+
+- Takes the service and create a "Deployment" file
+- if a port is declared, katenary creates a service (ClusterIP)
+- it a port is exposed, katenary creates a service (NodePort)
+- environment variables will be stored in `values.yaml` file
+- image, tags, and ingresses configuration are also stored in `values.yaml` file
+- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file (a `emptyDir` is used by default)
+- any other volume (local mount points) are ignored
+- `depends_on` needs that the pointed service declared a port. If not, you can use labels to inform katenary
+
+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
+
+After having installed `katenary`, the standard usage is to call:
+
+```bash
+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:
+```bash
+katenary convert -c file1.yaml -c file2.yaml
+```
+
+
+## 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.
+
+See this compose file:
+
+```yaml
+version: "3"
+
+services:
+    webapp:
+        image: php:8-apache
+        depends_on:
+        - database
+
+    database:
+        image: mariadb
+        environment:
+            MYSQL_ROOT_PASSWORD: foobar
+```
+
+In this case, `webapp` needs to know the `database` port because the `depends_on` points on it and Kubernetes has not (yet) solution to check the database startup. Katenary wants to create a `initContainer` to hit on the related service. So, instead of exposing the port in the compose definition, let's declare this to katenary with labels:
+
+
+```yaml
+version: "3"
+
+services:
+    webapp:
+        image: php:8-apache
+        depends_on:
+        - database
+
+    database:
+        image: mariadb
+        environment:
+            MYSQL_ROOT_PASSWORD: foobar
+        labels:
+            katenary.io/ports: 3306
+```
+