Merge pull request #27 from sftim/20210316_initial_docs

Import documentation

content/en/contact/_index.md

@@ -0,0 +1,25 @@
+---
+title: "Contact Us"
+linkTitle: "Contact"
+draft: false
+weight: 30
+menu:
+  main:
+    weight: 30
+---
+
+<!-- bodge to fix top of page padding -->
+<!-- better fix: make the Hugo / Docsy layout work -->
+<div style="min-height: 8rem;">&nbsp;</div>
+
+<div style="max-width: 60em; margin-left: auto; margin-right: auto;">
+
+The Shipwright contributors would love to hear from you! You can reach us in the following forums:
+
+- Users can discuss help, feature requests, or potential bugs at [[email protected]](https://lists.shipwright.io/archives/list/[email protected]/).
+  Click [here](https://lists.shipwright.io/admin/lists/shipwright-users.lists.shipwright.io/) to join.
+- Contributors can discuss active development topics at [[email protected]](https://lists.shipwright.io/archives/list/[email protected]/).
+  Click [here](https://lists.shipwright.io/admin/lists/shipwright-dev.lists.shipwright.io/) to join.
+- We can also be reached on Kubernetes Slack: [#shipwright](https://kubernetes.slack.com/messages/shipwright)
+
+</div>

content/en/docs/_index.md

@@ -3,20 +3,136 @@ title: "Documentation"
 linkTitle: "Documentation"
 draft: false
 weight: 20
+no_list: true
 menu:
   main:
     weight: 20
 ---
 
-Documentation can be found on GitHub at
-[shipwright-io/build](https://github.com/shipwright-io/build/blob/master/README.md).
 
-## Contact Us
 
-The Shipwright contributors would love to hear from you! You can reach us in the following forums:
+Shipwright is an extensible framework for building container images on Kubernetes.
 
-- Users can discuss help, feature requests, or potential bugs at [[email protected]](https://lists.shipwright.io/archives/list/[email protected]/).
-  Click [here](https://lists.shipwright.io/admin/lists/shipwright-users.lists.shipwright.io/) to join.
-- Contributors can discuss active development topics at [[email protected]](https://lists.shipwright.io/archives/list/[email protected]/).
-  Click [here](https://lists.shipwright.io/admin/lists/shipwright-dev.lists.shipwright.io/) to join.
-- We can also be reached on Kubernetes Slack: [#shipwright](https://kubernetes.slack.com/messages/shipwright)
+Shipwright supports popular tools such as Kaniko, Cloud Native Buildpacks, Buildah, and more!
+
+Shipwright is based around four elements for each build:
+
+1. Source code - the "what" you are trying to build
+1. Output image - "where" you are trying to deliver your application
+1. Build strategy - "how" your application is assembled
+1. Invocation - "when" you want to build your application
+
+## Comparison with local image builds
+
+Developers who use Docker are familiar with this process:
+
+1. Clone source from a git-based repository ("what")
+2. Build the container image ("when" and "how")
+
+  ```bash
+  docker build -t registry.mycompany.com/myorg/myapp:latest .
+  ```
+
+3. Push the container image to your registry ("where")
+
+  ```bash
+  docker push registry.mycompany.com/myorg/myapp:latest
+  ```
+
+## Shipwright Build APIs
+
+Shipwright's Build API consists of four core
+[CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions)
+(CRDs):
+
+1. [`Build`](/docs/api/build/) - defines what to build, and where the application should be delivered.
+1. [`BuildStrategy` and `ClusterBuildStrategy`](/docs/api/buildstrategies/) - defines how to build an application for an image
+   building tool.
+1. [`BuildRun`](/docs/api/buildrun/) - invokes the build.  
+   You create a `BuildRun` to tell Shipwright to start building your application.
+
+
+### Build
+
+The `Build` object provides a playbook on how to assemble your specific application. The simplest
+build consists of a git source, a build strategy, and an output image:
+
+```yaml
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: kaniko-golang-build
+  annotations:
+    build.build.dev/build-run-deletion: "true"
+spec:
+  source:
+    url: https://github.com/sbose78/taxi
+  strategy:
+    name: kaniko
+    kind: ClusterBuildStrategy
+  output:
+    image: registry.mycompany.com/my-org/taxi-app:latest
+```
+
+Builds can be extended to push to private registries, use a different Dockerfile, and more.
+
+### BuildStrategy and ClusterBuildStrategy
+
+`BuildStrategy` and `ClusterBuildStrategy` are related APIs to define how a given tool should be
+used to assemble an application. They are distinguished by their scope - `BuildStrategy` objects
+are namespace scoped, whereas `ClusterBuildStrategy` objects are cluster scoped.
+
+The spec of a `BuildStrategy` or `ClusterBuildStrategy` consists of a `buildSteps` object, which look and feel like Kubernetes container
+specifications. Below is an example spec for Kaniko, which can build an image from a
+Dockerfile within a container:
+
+```yaml
+# this is a fragment of a manifest
+spec:
+  buildSteps:
+    - name: build-and-push
+      image: gcr.io/kaniko-project/executor:v1.3.0
+      workingDir: /workspace/source
+      securityContext:
+        runAsUser: 0
+        capabilities:
+          add:
+            - CHOWN
+            - DAC_OVERRIDE
+            - FOWNER
+            - SETGID
+            - SETUID
+            - SETFCAP
+      env:
+        - name: DOCKER_CONFIG
+          value: /tekton/home/.docker
+      command:
+        - /kaniko/executor
+      args:
+        - --skip-tls-verify=true
+        - --dockerfile=$(build.dockerfile)
+        - --context=/workspace/source/$(build.source.contextDir)
+        - --destination=$(build.output.image)
+        - --oci-layout-path=/workspace/output/image
+        - --snapshotMode=redo
+      resources:
+        limits:
+          cpu: 500m
+          memory: 1Gi
+        requests:
+          cpu: 250m
+          memory: 65Mi
+```
+
+### BuildRun
+
+Each `BuildRun` object invokes a build on your cluster. You can think of these as a Kubernetes 
+`Jobs` or Tekton `TaskRuns` - they represent a workload on your cluster, ultimately resulting in a
+running `Pod`. See [`BuildRun`](/docs/buildrun/) for more details.
+
+## Further reading
+
+- [Configuration](/docs/configuration/)
+- Build controller observability
+  - [Metrics](/docs/metrics/)
+  - [Profiling](/docs/profiling/)