developer docs (#359)

* docs: replace components.md with architecture.md * developer docs * docs: adds developer guide for apprepository-controller * more docs * docs: adds developer overview doc * contributing doc changes * docs": telepresence is not a hard requirement * no more spam * renamed docs/developer/overview.md to docs/developer/README.md * docs: remove duplicate build instructions * fix ci test
vmware-tanzu · Jun 15, 2018 · 23b7198 · 23b7198
1 parent 942b809
commit 23b7198
Show file tree

Hide file tree

Showing 22 changed files with 658 additions and 188 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -37,7 +37,7 @@ jobs:
     install: yarn install --cwd=dashboard --frozen-lockfile
     script:
     - yarn --cwd=dashboard run lint
-    - yarn --cwd=dashboard run test --maxWorkers=4 --coverage
+    - CI=true yarn --cwd=dashboard run test --maxWorkers=4
 
   # parallel build stages
   - &cliBuild

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,63 @@
+# Contributing
+
+When contributing to Kubeapps, please first discuss the change you wish to make via an issue with this repository before making a change.
+
+Please note we have a code of conduct, please follow it in all your interactions with the project.
+
+## Pull Request Process
+
+1. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
+2. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
+3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
+4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
+
+## Code of Conduct
+
+### Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+### Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+### Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+### Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at **ara AT bitnami DOT com**. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+### Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/
diff --git a/Makefile b/Makefile
@@ -11,16 +11,7 @@ EMBEDDED_STATIC = generated/statik/statik.go
 
 default: kubeapps
 
-kubeapps: $(EMBEDDED_STATIC)
-	$(GO) build -o $(BINARY) $(GO_FLAGS) $(IMPORT_PATH)
-
-test: $(EMBEDDED_STATIC)
-	$(GO) test $(GO_PACKAGES)
-
-$(EMBEDDED_STATIC): static/kubeapps-objs.yaml
-	# force compilation on current OS
-	GOOS= $(GO) build -o statik ./vendor/github.com/rakyll/statik/statik.go
-	$(GO) generate
+all: kubeapps kubeapps/dashboard kubeapps/chartsvc kubeapps/chart-repo kubeapps/apprepository-controller
 
 static/kubeapps-objs.yaml:
 	KUBEAPPS_VERSION=$${VERSION:-latest} ;\
@@ -30,21 +21,43 @@ static/kubeapps-objs.yaml:
 	KUBECFG_JPATH=./manifests/lib:./manifests/vendor/kubecfg/lib:./manifests/vendor/ksonnet-lib \
 		kubecfg show -V VERSION=$$KUBEAPPS_VERSION -V KUBELESS_VERSION=$$KUBELESS_VERSION manifests/kubeapps.jsonnet > static/kubeapps-objs.yaml
 
-test-dashboard:
-	yarn --cwd dashboard/ run test
+$(EMBEDDED_STATIC): static/kubeapps-objs.yaml
+	# force compilation on current OS
+	GOOS= $(GO) build -o statik ./vendor/github.com/rakyll/statik/statik.go
+	$(GO) generate
+
+kubeapps: $(EMBEDDED_STATIC)
+	$(GO) build -o $(BINARY) $(GO_FLAGS) $(IMPORT_PATH)
 
 kubeapps/%:
 	docker build -t kubeapps/$*:$(VERSION) -f cmd/$*/Dockerfile .
+
 kubeapps/dashboard:
 	docker build -t kubeapps/dashboard:$(VERSION) -f dashboard/Dockerfile dashboard/
 
+test: $(EMBEDDED_STATIC)
+	$(GO) test $(GO_PACKAGES)
+
+test-all: test-kubeapps test-chartsvc test-chart-repo test-apprepository-controller test-dashboard
+
+test-kubeapps:
+	$(GO) test -v $(IMPORT_PATH)
+
+test-dashboard:
+	yarn --cwd dashboard/ install --frozen-lockfile
+	yarn --cwd=dashboard run lint
+	CI=true yarn --cwd dashboard/ run test
+
+test-%:
+	$(GO) test -v $(IMPORT_PATH)/cmd/$*
+
 fmt:
 	$(GOFMT) -s -w $(GO_FILES)
 
 vet:
 	$(GO) vet $(GO_PACKAGES)
 
 clean:
-	$(RM) ./kubeapps ./chart-repo ./statik $(EMBEDDED_STATIC) static/kubeapps-objs.yaml
+	$(RM) ./kubeapps ./statik $(EMBEDDED_STATIC) static/kubeapps-objs.yaml
 
-.PHONY: default test test-dashboard fmt vet clean build-prep chart-repo kubeapps $(EMBEDDED_STATIC) static/kubeapps-objs.yaml
+.PHONY: default all test-all test test-dashboard fmt vet clean build-prep chart-repo kubeapps $(EMBEDDED_STATIC) static/kubeapps-objs.yaml
diff --git a/README.md b/README.md
@@ -28,7 +28,7 @@ These commands will deploy Kubeapps in your cluster and launch a browser with th
 
 ![Dashboard login page](img/dashboard-login.png)
 
-Access to the dashboard requires a Kubernetes API token to authenticate with the Kubernetes API server. Read the [Access Control](docs/access-control.md) documentation for more information on configuring users for Kubeapps.
+Access to the dashboard requires a Kubernetes API token to authenticate with the Kubernetes API server. Read the [Access Control](docs/user/access-control.md) documentation for more information on configuring users for Kubeapps.
 
 The following commands create a ServiceAccount and ClusterRoleBinding named `kubeapps-operator` which will enable the dashboard to authenticate and manage resources on the Kubernetes cluster:
 
@@ -43,7 +43,7 @@ Use the following command to reveal the authorization token that should be used
 kubectl get secret $(kubectl get serviceaccount kubeapps-operator -o jsonpath='{.secrets[].name}') -o jsonpath='{.data.token}' | base64 --decode
 ```
 
-**NOTE**: It's not recommended to create cluster-admin users for Kubeapps. Please refer to the [Access Control](docs/access-control.md) documentation to configure more fine-grained access.
+**NOTE**: It's not recommended to create cluster-admin users for Kubeapps. Please refer to the [Access Control](docs/user/access-control.md) documentation to configure more fine-grained access.
 
 ![Dashboard main page](img/dashboard-home.png)
 
@@ -62,76 +62,27 @@ kubectl delete serviceaccount kubeapps-operator
 
 ## Installation
 
-Get the latest release of Kubeapps Installer on the [Github releases](https://github.com/kubeapps/kubeapps/releases) page.
-
-Alternatively, when you have configured a proper Go environment (refer to the first two steps of [Build from Source](#build-from-source) section), the latest Kubeapps Installer can be get-able from source:
-
-```bash
-go get github.com/kubeapps/kubeapps
-```
+Get the latest release of the Kubeapps installer for for platform from the [releases](https://github.com/kubeapps/kubeapps/releases) page, add it to your `PATH` and you're ready to go.
 
 ## Build from Source
 
-The Kubeapps Installer is a CLI tool written in Go that will deploy the Kubeapps components into your cluster.
-You can build the latest Kubeapps Installer from source by following the steps below:
-
-* Visit [the Go website](https://golang.org), download the most recent [binary distribution of Go](https://golang.org/dl/) and install it following the [official instructions](https://golang.org/doc/install).
-
-  > The remainder of this section assumes that Go is installed in `/usr/local/go`. Update the paths in subsequent commands if you used a different location.
-
-* Set the Go environment variables:
-
-  ```bash
-  export GOPATH=$HOME/gopath
-  export PATH=$GOPATH/bin:$PATH
-  ```
-
-* Install kubeapps build dependencies:
-
-  ```bash
-  go get github.com/ksonnet/kubecfg
-  ```
+Please refer to the [Kubeapps Build Guide](docs/developer/build.md) for instructions on setting up the build environment and building Kubeapps from source.
 
-* Create a working directory for the project:
+## Developer Documentation
 
-  ```bash
-  working_dir=$GOPATH/src/github.com/kubeapps/
-  mkdir -p $working_dir
-  ```
-
-* Clone the Kubeapps source repository:
-
-  ```bash
-  cd $working_dir
-  git clone --recurse-submodules https://github.com/kubeapps/kubeapps
-  ```
-
-* Build the Kubeapps binary and move it to a location in your path:
-
-  ```bash
-  cd kubeapps
-  make kubeapps
-  ```
-
-## Running tests
-
-Run Go tests using `make test`. See [dashboard documentation](dashboard/README.md) for information on running dashboard tests.
-
-```bash
-make test
-```
+Please refer to the [Kubeapps Developer Documentation](docs/developer/README.md) for instructions on setting up the developer environment for developing Kubeapps components.
 
 ## Next Steps
 
-[Use the Kubeapps Dashboard](docs/dashboard.md) to easily manage the deployments created by Helm in your cluster and to manage your Kubeless functions, or [look under the hood to see what's included in Kubeapps](docs/components.md).
+[Use the Kubeapps Dashboard](docs/user/dashboard.md) to easily manage the deployments created by Helm in your cluster and to manage your Kubeless functions, or [look under the hood to see what's included in Kubeapps](docs/architecture/overview.md).
 
-In case of difficulties installing Kubeapps, find [more detailed installation instructions](docs/install.md).
+In case of difficulties installing Kubeapps, find [more detailed installation instructions](docs/user/install.md).
 
-For a more detailed and step-by-step introduction to Kubeapps, read our [introductory walkthrough](docs/getting-started.md).
+For a more detailed and step-by-step introduction to Kubeapps, read our [introductory walkthrough](docs/user/getting-started.md).
 
 ## Useful Resources
 
-* [Walkthrough for first-time users](docs/getting-started.md)
-* [Detailed installation instructions](docs/install.md)
-* [Kubeapps Dashboard documentation](docs/dashboard.md)
-* [Kubeapps components](docs/components.md)
+* [Walkthrough for first-time users](docs/user/getting-started.md)
+* [Detailed installation instructions](docs/user/install.md)
+* [Kubeapps Dashboard documentation](docs/user/dashboard.md)
+* [Kubeapps components](docs/architecture/overview.md)
diff --git a/dashboard/README.md b/dashboard/README.md
diff --git a/...osals/authentication-and-authorization.md → ...osals/authentication-and-authorization.md b/...osals/authentication-and-authorization.md → ...osals/authentication-and-authorization.md
diff --git a/docs/design-proposals/image_0.png → ...architecture/design-proposals/image_0.png b/docs/design-proposals/image_0.png → ...architecture/design-proposals/image_0.png
diff --git a/docs/design-proposals/image_1.png → ...architecture/design-proposals/image_1.png b/docs/design-proposals/image_1.png → ...architecture/design-proposals/image_1.png
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -0,0 +1,39 @@
+# The Kubeapps Overview
+
+This document describes the Kubeapps architecture at a high level.
+
+## The purpose of Kubeapps
+
+Kubeapps is a Kubernetes dashboard that provides simple browse and click deployment of applications and Kubeless functions. The Kubeapps dashboard can do the following:
+
+    - List charts from Helm chart repositories
+    - Install and uninstall Helm charts from repositories
+    - Manage installed chart releases
+    - Create, edit and test Kubeless functions
+    - Browse, provision and manage external cloud services
+
+## Components
+
+### Kubeapps installer
+
+The Kubeapps installer is a command-line tool for installing, upgrading and uninstalling the Kubeapps in-cluster components. The tool is written in the Go programming language and the Kubernetes manifests are written in the Jsonnet data templating language.
+
+### Kubeapps dashboard
+
+At the heart of Kubeapps is a in-cluster Kubernetes dashboard that provides you a simple browse and click experience for installing applications packaged as Helm charts. It also provides you a simple and easy to use web interface to develop, test and deploy Kubeless functions.
+
+Additionally, the dashboard integrates with the [Kubernetes service catalog](https://github.com/kubernetes-incubator/service-catalog) and enables you to browse and provision cloud services via the [Open Service Broker API](https://github.com/openservicebrokerapi/servicebroker).
+
+The dashboard is written in the Javascript programming language and is developed using the React Javascript library.
+
+### Helm CRD
+
+[Helm CRD](https://github.com/bitnami-labs/helm-crd) is an experimental Kubernetes controller for Helm releases. It enables cluster operators to secure the Helm tiller server and is used to install, upgrade and uninstall Helm charts.
+
+The controller is developed independently of Kubeapps at [bitnami-labs/helm-crd](https://github.com/bitnami-labs/helm-crd) and is written in the Go programming language.
+
+### Kubeless
+
+[Kubeless](http://kubeless.io/) is a Kubernetes-native serverless framework that lets you deploy small bits of code (functions) without having to worry about the underlying infrastructure. It leverages Kubernetes resources to provide auto-scaling, API routing, monitoring, troubleshooting and more.
+
+Kubeless is also written in the Go programming language and is also developed independently of Kubeapps at [kubeless/kubeless](https://github.com/kubeless/kubeless).
diff --git a/docs/components.md b/docs/components.md
diff --git a/docs/developer/README.md b/docs/developer/README.md
@@ -0,0 +1,25 @@
+# The Kubeapps Components
+
+### Kubeapps installer
+
+The Kubeapps installer is a command-line tool for installing, upgrading and uninstalling the Kubeapps in-cluster components. The tool is written using the Go programming language and the Kubernetes manifests are written in the Jsonnet data templating language.
+
+Please refer to the [Kubeapps Installer Developer Guide](kubeapps.md) for the developer setup.
+
+### Kubeapps dashboard
+
+The dashboard is the main UI component of the Kubeapps project. Written in Javascript, the dashboard uses the React Javascript library for the frontend.
+
+Please refer to the [Kubeapps Dashboard Developer Guide](dashboard.md) for the developer setup.
+
+### chart-svc
+
+The `chartsvc` component is a micro-service that creates a API endpoint for accessing the metadata for charts in Helm chart repositories that's populated in a MongoDB server.
+
+Please refer to the [Kubeapps ChartSVC Developer Guide](chartsvc.md) for the developer setup.
+
+### chart-repo
+
+The `chart-repo` component is tool that scans a Helm chart repository and populates chart metadata in a MongoDB server. This metadata is then served by the `chartsvc` component.
+
+Please refer to the [Kubeapps chart-repo Developer Guide](chart-repo.md) for the developer setup.