From c06389ce568a318d474c563fa8633e01883cd95c Mon Sep 17 00:00:00 2001
From: Patrick Sy <patrick.sy@telekom.de>
Date: Wed, 16 Oct 2024 10:36:58 +0200
Subject: [PATCH] docs(dagger): Added some more detailed explanations for
 clarification

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index e420292..c1ec897 100644
--- a/README.md
+++ b/README.md
@@ -61,14 +61,38 @@ dagger call build --source=.
 ```
 
 This runs the `build` function defined in `dagger/src/index.ts` and passes `.`
-as the `source` parameter of that function.
+as the `source` parameter of that function. The return type of this function is
+a `Container` type which just prints some general information on the resulting
+container when called this way.
+
+```
+_type: Container
+defaultArgs: []
+entrypoint:
+    - helloworld
+mounts: []
+platform: linux/amd64
+user: ""
+workdir: ""
+```
+
+The `Container` has to be consumed by other functions to actually export it to
+some registry or run it. The same is true for other types like `File` and
+`Directory` which also only expose the actual artifacts through effectful
+functions, thus the FP-like feeling. Only 'simple' strings can be exposed on
+the shell. Consequently, pipelining on the shell seems not to be a common
+thing.
+
+Dagger separates the containerized build environment from the host system.
+Unless specifically specified, like with `--source=.`, dagger does not expose
+host resources.
 
 > Camel Case function names in the TS setup are available in Kebab Case on the
 > shell (same applies for Go and Python). This does not only apply to your own
 > declared functions but to all functions available on the returned data types.
 >
 > ```typescript
-> this.build(source).asService().up({ ports: "8080:8080" });
+> this.build(source).asService().up({ ports: "8080:9000" });
 > ```
 >
 > becomes
@@ -76,6 +100,8 @@ as the `source` parameter of that function.
 > ```shell
 > dagger call build --source=. as-service up --ports=8080:9000
 > ```
+>
+> Dagger calls this function chaining.
 
 > After running a dagger command the Dagger Engine stays alive as a local
 > container waiting for the next call.
@@ -115,6 +141,10 @@ Push the container image to some registry:
 dagger call build --source=. publish --address=mtr.devops.telekom.de/...
 ```
 
+This call makes use of the aforementioned chaining capabilities. One could
+create a custom function to chain calls within the config or just chain call in
+a shell call.
+
 ### Deployment to Kubernetes
 
 Dagger at its core does not provide tooling to deploy artifacts to kubernetes
@@ -136,10 +166,14 @@ A critical problem however is the fact that the dagger engine requires running
 in privileged mode, see
 [FAQ](https://docs.dagger.io/faq#can-i-run-the-dagger-engine-as-a-rootless-container).
 Depending on the platform this might be a dealbreaker due to security issues.
-If the platform does not provide a somewhat isolated vm environment, the
-suggested setup includes hosting one or more shared dagger engines within the
-platform, see the Gitlab CI kubernetes
+If the platform does not provide a somewhat isolated vm environment that is
+capable of running containers itself (in this case the dagger cli would spawn
+its own instance of the dagger engine), the suggested setup includes hosting
+one or more shared dagger engines within the platform, see the Gitlab CI
+kubernetes
 [example](https://docs.dagger.io/integrations/gitlab#kubernetes-executor).
+Security concerns of using a shared instance of the dagger engine should be
+investigated if one wants to go down this road.
 
 ## Conclusion