add doc

README.md

@@ -9,16 +9,18 @@ build integrates all the tools we use to work with development & clouds. We know
 
 But we have chosen to create & use one more due to this reasons:
 
-* Our builds tend to get more and more complex. So we decided that implementing build is worth to use real clojure.
-* We like simple setup & fast startup. For this reason we've chosen babashka
-* We believe in good input validation & good messages. For this reason we use the coole clojure-spec.
-* As DevOps we are using many tools, all of them should be supported:
+* **No immature scripting languages**: Our builds tend to be complex. So we decided that implementing build is worth to be done in real dev-language like clojure.
+* **Fast runtime**: We like runtime with simple setup & fast startup. For this reason we've chosen babashka
+* **Input validation**: We believe in good input validation & good messages. For this reason we use the coole clojure-spec for build config.
+* **Fast feedback**: The DevOps experience local compared to CI should be as equal as possible. We like working local for fast feedback cycles.
+* **No source pollution**: All generation stuff happens in a separated build dir.
+* **Tool Support**: As DevOps we are using many tools, all of them should be supported:
   * gitops & direnv: State of environments and systems is represented by a git repo. State is applied automatically.
-  * terragrunt + opentofu: for setting up the plain infrastructure around.
-  * docker + podman: for creating images
-  * c4k-* or helm: for generating kubernetes manifests
-  * provs: for setting up small single-node k3s clusters
-  * gopass: for credential management on devops computers
+  * terragrunt + opentofu: For setting up the plain infrastructure around.
+  * docker + podman: For creating images
+  * c4k-* or helm: For generating kubernetes manifests
+  * provs: For one-shoot setup small single-node k3s clusters and a first application.
+  * gopass: For credential management on devops computers
   * cloud providers: hetzner, digitalocean or aws
 
 ## Status
@@ -27,8 +29,20 @@ Unstable
 
 ## Try out
 
-
+We use direnv for setting the environments:
+```bash
+export STAGE=test
+export HETZNER_API_KEY=$(gopass show path-to-hetzner-api-token)
+export DO_API_KEY=$(gopass show path-to-do-api-key)
+export DO_SPACES_ACCESS_ID=$(gopass show path-to-do-s3-key id)
+export DO_SPACES_SECRET_KEY=$(gopass show path-to-do-s3-key secret)
+export TERRAGRUNT_TFPATH=tofu
+export TERRAGRUNT_DOWNLOAD=~/.terragrunt
+export TERRAGRUNT_PROVIDER_CACHE=1
 ```
+
+Build taske looks like this:
+```clj
 {:deps {org.clojure/spec.alpha {:mvn/version "0.4.233"}
         orchestra/orchestra {:mvn/version "2021.01.01-1"}
         org.domaindrivenarchitecture/build {:mvn/version "0.1.1-SNAPSHOT"}}
@@ -58,6 +72,45 @@ Unstable
                        :version "4.11.8-dev"
                        :debug true})}}}
 ```
+
+Execute the build
+```bash
+bb plan [module]
+```
+
+The gitops dir layout looks like
+```bash
+.
+├── infrastructure
+│   └── tenant
+│       ├── prod
+│       └── test
+│           ├── bb.edn
+│           ├── jitsi
+│           │   ├── main.tf
+│           │   └── terragrunt.hcl
+│           ├── statistics
+│           │   ├── main.tf
+│           │   └── terragrunt.hcl
+│           └── terragrunt.hcl
+├── modules
+│   └── app
+│       ├── main.tf
+│       ├── registry.tf
+│       ├── remote_state.tf
+│       └── variables.tf
+└── target
+    └── test
+        ├── jitsi
+        │   ├── generated_backend.tf
+        │   ├── generated_provider.tf
+        │   ├── generated_registry.tf
+        │   ├── generated_variables.tf
+        │   ├── main.tf
+        │   └── terragrunt.hcl
+        └── terragrunt.hcl
+```
+
 ## Development & mirrors
 
 Development happens at: https://repo.prod.meissa.de/meissa/build