Add documentation

docs/_index.md

+---
+title: Headlamp
+---
+
+Headlamp is an easy-to-use and extensible Kubernetes web UI.
+
+Headlamp was created to be a Kubernetes web UI that has the traditional functionality of other
+web UIs/dashboards available (i.e. to list and view resources) as well as other features.
+
+Headlamp can be used in-cluster, where it's accessed through a web browser,
+or as a desktop application (using the information defined in the user's
+kubeconfig).

docs/contributing.md

-# Contribution Guidelines
+---
+title: Contribution Guidelines
+linktitle: Contributing
+---
 
-This section serves as an introduction on how to contribute to Headlamp; getting started, development practices, filing issues, etc..
-It assumes you have cloned this repository (or your own Github fork).
+This section has information on how to contribute to Headlamp. It assumes you have cloned
+this repository (or your own Github fork).
 
 Any contributions to the project are accepted under the terms of the project's
 license ([Apache 2.0](../LICENSE)).
@@ -10,6 +13,13 @@ license ([Apache 2.0](../LICENSE)).
 
 Please refer to the Kinvolk [Code of Conduct](https://github.com/kinvolk/contribution/blob/master/CODE_OF_CONDUCT.md).
 
+## Development practices
+
+The Headlamp project follows the [Kinvolk Contribution Guidelines](https://github.com/kinvolk/contribution)
+which promotes good and consistent contribution practises across Kinvolk's
+projects. Before start contributing, and in addition to this section, please
+read those guidelines.
+
 ## Filing an issue or feature request
 
 Please use the [project's issue tracker](https://github.com/kinvolk/headlamp/issues) for filing any bugs you find or features
@@ -21,54 +31,7 @@ If you have a complex contribution in mind (meaning changes in the architecture
 or a lot of LOC changed), it is advisable to first file a Github issue and
 discuss the implementation with the project's maintainers.
 
-## Build the code
-
-Headlamp is composed by a `backend` and a `frontend`.
-
-You can build both the `backend` and `frontend` by running.
-
-```bash
-make
-```
-
-Or individually:
-
-```bash
-make backend
-```
-
-and
-
-```bash
-make frontend
-```
-
-## Run the code
-
-The quickest way to get the `backend` and `frontend` running for development is
-the following (respectively):
-
-```bash
-make run-backend
-```
-
-and in a different terminal instance:
-
-```bash
-make run-frontend
-```
-
-## Build a Docker image
-
-The following command builds a Docker image for Headlamp from the current
-source. It will run the `frontend` from a `backend`'s static server, and
-options can be appended to the main command as arguments.
-
-```bash
-make image
-```
-
-### Coding style
+## Coding style
 
 The coding style for `backend` and `frontend` should be consistent.
 For helping and verifying that, we have go and js linters.

docs/development/_index.md

+---
+title: Development
+---
+
+This is a quickstart guide for building and running Headlamp for development.
+
+Please make sure you read the [Contribution Guidelines](../contributing.md) as well
+before starting to contribute to the project.
+
+## Build the code
+
+Headlamp is composed by a `backend` and a `frontend`.
+
+You can build both the `backend` and `frontend` by running.
+
+```bash
+make
+```
+
+Or individually:
+
+```bash
+make backend
+```
+
+and
+
+```bash
+make frontend
+```
+
+## Run the code
+
+The quickest way to get the `backend` and `frontend` running for development is
+the following (respectively):
+
+```bash
+make run-backend
+```
+
+and in a different terminal instance:
+
+```bash
+make run-frontend
+```
+
+## Build a Docker image
+
+The following command builds a Docker image for Headlamp from the current
+source. It will run the `frontend` from a `backend`'s static server, and
+options can be appended to the main command as arguments.
+
+```bash
+make image
+```
+
+### Shipping plugins in the Docker image
+
+Since the Headlamp server has an option (`-plugins-dir`) for indicating where to find any plugins,
+a deployment of Headlamp using the Docker image can mount a plugins folder
+and point to it by using the mentioned option.
+
+An alternative is to build an image that ships some plugins in it. For that,
+just create a plugins folder in the Headlamp project directory as the Dockerfile
+will include it and point to it by default.

docs/development/backend.md

+---
+title: Backend
+weight: 5
+---
+
+Headlamp's backend is written in Go and is in charge of redirecting the
+client requests to the right clusters, as well as to return any available
+plugins for the client to use.
+
+The backend most basic and essential function is to read the cluster information
+from the given configuration, and set up proxies to the defined clusters as
+well as endpoints to them. This means that instead of having a set of
+endpoints related to the functionality available to the client, it simply
+redirects the requests to the defined proxies.
+
+## Building and running
+
+The backend (Headlamp's server) can be quickly built using:
+
+```bash
+make backend
+```
+
+Once built, it can be run in development mode (insecure / don't use in production) using:
+
+
+```bash
+make run-backend
+```

docs/development/frontend.md

+---
+title: Frontend
+weight: 5
+---
+
+The frontend is written in Typescript and React, as well as a few other important modules like:
+* Material UI
+* React Router
+* Redux
+* Redux Sagas
+
+## Building and running
+
+The frontend can be quickly built using:
+
+```bash
+make frontend
+```
+
+Once built, it can be run in development mode (auto-refresh) using:
+
+
+```bash
+make run-frontend
+```
+
+This command leverages the `create-react-app`'s start script that launches
+a development server for the frontend (by default at `localhost:3000`).

docs/development/plugins/_index.md

+---
+title: Plugins
+linkTitle: Plugins
+---
+
+Plugins are one of the key features of Headlamp and allow to modify change what and how information is displayed, as well as other functionality. The ultimate goal of the plugins system is to allow vendors to build and deploy Headlamp with extra functionality without having to maintain a fork of the project.
+
+# Developing Plugins
+
+Plugins are supposed to be built and shipped out-of-tree, i.e. instead of managing the plugins'
+code within the Headlamp project or a Headlamp fork (which would require
+always rebuilding/maintaining Headlamp when changing a plugin), they're
+supposed to be built outside of the project and just pointed to by the
+Headlamp's server.
+
+*⚠️ IMPORTANT FOR DEVS:* The plugins system and plugins lib is still in the process of being
+consolidated. This means that 1) it's subject to change, 2) you are very
+welcome to contribute to it with different use cases and/or development.

docs/development/plugins/building.md

+---
+title: Building and Shipping Plugins
+linktitle: Building & Shipping
+---
+
+## Active development / In-tree build
+
+During development however, the workflow of 1. building the plugins outside
+of the project; 2. copying to a plugins folder; 3. running Headlamp pointing
+to that folder, is not a great development user-experience.
+
+While we are planning a smarter way to develop plugins outside of the project's tree
+and having them automatically built and served to the frontend, we have to
+use the work around of developing/testing them within the project (before
+building and shipping them externally once ready).
+
+For that, you can develop your plugins inside the `frontend/src/plugin/plugins` folder. E.g. if your plugin is called `MyPlugin`, then your plugin
+structure should be as follows:
+
+  ```
+  frontend/src/plugin/plugins/MyPlugin/index.tsx
+  ```
+
+## Out-of-tree build
+
+Once your plugin is working as intended, it should be compiled our of the
+Headlamp project. The `index.tsx` (or other Typescript/Javascript extensions)
+should be in its own module like:
+
+  ```
+  MyPlugin/
+    src/
+      index.tsx
+    package.json
+  ```
+
+Feel free to use `npm create` for getting the base structure/files right.
+
+For helping with compiling the plugin code we have the
+[@kinvolk/headlamp-plugin](https://www.npmjs.com/package/@kinvolk/headlamp-plugin),
+which should be installed as a dev dependency:
+
+```bash
+npm install --save-dev @kinvolk/headlamp-plugin
+```
+
+Once that's done, simply change your `scripts` element to use the `headlamp-plugin` script:
+
+```json
+"scripts": {
+  "build": "headlamp-plugin"
+}
+```
+
+This way, when you run `npm run build`, the plugin will be compiled to a file
+within the module called `dist/main.js`
+
+## Shipping / Deploying Plugins
+
+Once we have the plugin or plugins compiled, they should be included in
+Headlamp by having them in a "plugins directory" which should be passed to
+Headlamp's server.
+
+For example, if we have compiled 3 plugins called MyPlugin1, MyPlugin2, and
+MyPlugin3, they should be added to a directory in the following structure:
+
+  ```
+  plugins/
+    MyPlugin1/
+      main.js
+    MyPlugin2/
+      main.js
+    MyPlugin3/
+      main.js
+  ```
+
+Then, when running Headlamp's server, the `-plugin-dir` option should point
+to the directory:
+
+```bash
+./server -plugins-dir=/path/to/plugins/
+```

docs/development/plugins/functionality.md

+---
+title: Plugins Functionality
+linktitle: Functionality
+---
+
+Headlamp's plugins exist for changing or adding functionlity related to
+the user interface and experience.
+
+## Plugins Lib
+
+Headlamp exposes a `pluginLib` object in the global object `window`.
+A number of modules, both from Headlamp, or representing Headlamp's common
+dependencies are included in the `pluginLib`.
+
+Thus, plugins should only use dependencies that are not yet provided by Headlamp.
+
+
+### Modules
+
+External modules available currently in the `pluginLib` are:
+
+* React
+* Iconify
+* ReactRedux
+* MuiCore (Material UI's core module)
+* MuiStyles (Material UI's styles module)
+* Lodash
+
+Apart from the external modules above, the `pluginLib` contains of course
+modules that are related to Headlamp, so developers can use the cluster and
+web UI related functionality. Those modules are:
+
+* K8s
+* CommonComponents
+
+This means that you can just declare a `const React = window.pluginLib.React` in order to use
+React without having to import it.
+
+### Registration
+
+Apart from the modules mentioned above, Headlamp also adds an important method
+for registering plugins (`window.registerPlugin`).
+
+## Funcionality
+
+The plugin registers makes functionality available to plugins in an easy way.
+
+The idea is to make more and more functionality available to plugins. Here is
+what we have so far:
+
+### Sidebar Items
+
+```typescript
+registerSidebarItem(parentName: string, itemName: string,
+                    itemLabel: string, url: string,
+                    opts = {useClusterURL: true})
+```
+
+This method allows to set entries in the sidebar.
+
+The arguments are as follows:
+
+* `parentName`: The name of the parent entry. If the string is empty, then there is no parent,
+and that means the entry is a top-level one. For knowing which names exist
+already in the Sidebar, at the moment you have to check the configuration for that component, which can be found in Headlamp's `src/components/Sidebar.tsx`.
+* `itemName`: The logical name for the item, i.e. the name other sub-entries will use
+when setting this item as a parent.
+* `itemLabel`: The text to be displayed for the entry in the Sidebar.
+* `url`: The URL to go to when clicking this entry.
+* `opts`: The options related to registering this item. At the moment, only
+the `useClusterUrl` (defaults to `true`) can be used. This option indicates
+whether the URL we are using for this entry should be prefixed with the
+current cluster URL or not. Most cluster related actions should have URLs
+that are prefixed by the cluster name and that's managed automatically
+with this option.
+
+### Routes
+
+```typescript
+registerRoute(routeSpec: Route)
+```
+
+```typescript
+interface Route {
+  path: string;
+  exact?: boolean;
+  noCluster?: boolean;
+  noAuthRequired?: boolean;
+  sidebar: string | null;
+  component: () => JSX.Element;
+}
+```
+
+This method allows to register a route (i.e. a known URL that resolves to
+a component displayed in Headlamp's main area).
+
+The `routeSpec` is an object with the following members:
+
+* `path`: The URL path for the route.
+* `exact` (optional): There it should be an exact match between the URL's path and the
+one defined in the route spec (see [ReactRouter](https://reactrouter.com/native/api/Route/exact-bool)'s docs for more context). By default it is `false`.
+* `noCluster` (optional): Whether the route doesn't belongs to a cluster (in which
+case the URL produced for it will have the cluster prefix). By default it is `false`.
+* `noAuthRequired` (optional): Whether authentication is not required for this route
+(example, non-cluster routes such as settings). By default it is `false`.
+* `sidebar`: Which sidebar entry to select when this route is on (the value used should be an item
+name of the sidebar).
+* `component`: The component to render in Headlamp's main area.
+
+### Details Views' Header Actions
+
+```typescript
+registerDetailsViewHeaderAction(actionName: string,
+                                actionFunc: (item: object) => JSX.Element | null)
+```
+
+This method allows to add a component to the top right area of details views
+(in the area of the screenshot below that's highlighted as yellow).
+
+![screenshot of the header showing two actions](./header_actions_screenshot.png)
+
+Details views are the views used for displaying information about each
+cluster's resource.
+
+The arguments are as follows:
+
+* `actionName`: The name for this action.
+* `actionFunc`: A function that takes an item and returns an element (or null, if nothing should
+be done).
+
+### App Bar Actions
+
+```typescript
+registerAppBarAction(actionName: string, actionFunc: () => JSX.Element | null))
+```
+
+This method allows to add a component to the top right area of the app bar
+(top bar).
+
+The arguments are as follows:
+
+* `actionName`: The name for this action.
+* `actionFunc`: A function that returns an element.

docs/development/plugins/how-to.md

+---
+title: How to create a Plugin
+linktitle: How-to
+---
+
+This section will walk you through a basic plugin development.
+
+## Types
+
+If you are using Typescript for developing the plugin, the `@kinvolk/headlamp-plugin` package does
+ship some type declarations in `@kinvolk/headlamp-plugin/types`.
+Please notice that the whole external plugin mechanics are still in an early development phase
+and thus only the actual type declarations (and not the corresponding code) is shipped in this package at the moment.
+
+
+```typescript
+import { Plugin } from '@kinvolk/headlamp-plugin/types/plugin/index.d';
+```
+
+## Plugin Class
+
+Plugins are classes that register actions when they are initialized.
+
+A plugin class needs an `initialize` method which receives a `register`
+class that offers ways to register different types of actions in the web UI.
+
+Besides declaring the plugin, an instance of it needs to be registered using
+the `window.registerPlugin` method.
+
+The following example will show a basic plugin declaration and registration
+in a file that should match the `src/index.tsx` structure explained in the
+[building](./building) section.
+
+
+```typescript
+import { Plugin } from '@kinvolk/headlamp-plugin/types/plugin/index.d';
+import Registry from '@kinvolk/headlamp-plugin/types/plugin/registry';
+
+class MyPlugin implements Plugin {
+  initialize(register: Registry) {
+    // Actual actions registration goes here
+
+    // At the moment the return value is ignored, but it will be used
+    // to determine whether the plugin could be initialized.
+    return true;
+  }
+}
+
+window.registerPlugin('my-plugin', new MyPlugin());
+```
+
+## Plugin Example
+
+Let's create a plugin that just gets the number of pods in the cluster and
+displays that information in the top bar (i.e. registers an "app bar action").
+
+```tsx
+import { Plugin } from '@kinvolk/headlamp-plugin/types/plugin/index.d';
+import Registry from '@kinvolk/headlamp-plugin/types/plugin/registry.d';
+
+const pluginLib = window.pluginLib;
+const React = window.pluginLib.React;
+const K8s = pluginLib.K8s.ResourceClasses;
+const { Typography } = pluginLib.MuiCore;
+
+function PodCounter() {
+  const [pods, error] = K8s.Pod.useList();
+  const msg = pods === null ? 'Loading…' : pods.length.toString();
+
+  return (
+      <Typography color="textPrimary">{!error ? `# Pods: ${msg}` : 'Uh, pods!?'}</Typography>
+  );
+}
+
+class PodCounterPlugin implements Plugin {
+  initialize(register: Registry) {
+    register.registerAppBarAction('monitor', () =>
+      <PodCounter />
+    );
+
+    return true;
+  }
+}
+
+window.registerPlugin('pod-counter', new PodCounterPlugin());
+```
+
+Here is the result, running Headlamp with this plugin and using with a Minikube cluster:
+
+![screenshot showing a label on the top bar with the number of pods available](./podcounter_screenshot.png)
+
+Please refer to the [functionality](./functionality) section for learning about
+the different functionality that is available to plugins by the registry.

docs/installation/_index.md

+---
+title: Installation / Deployment
+linktitle: Installation
+weight: 2
+---
+
+Headlamp can be deployed in a Kubernetes cluster, or run as a desktop application.
+
+Please check the guides in this section for installing the desktop application
+or deploying Headlamp in your cluster.

docs/installation/desktop/_index.md

+---
+title: Desktop App Installation
+weight: 100
+---
+
+Headlamp can be run as a desktop application, for users who don't want to
+deploy it in cluster, or those who want to manage unrelated clusters locally.
+
+Currently there are desktop apps for [Linux](./linux-installation) and [Mac](./mac-installation). A Windows version is coming soon too.
+
+Please check the following guides for the installation in your desired platform.
+
+## Access using OIDC
+
+OIDC has a feature makes more sense when
+[running Headlamp in a cluster](../in-cluster.md) as it will allow cluster operators to just
+give users a URL that they can use for logging in and access Headlamp.
+However, if you have your kube config set to use OIDC for the authentication (because you already
+authenticated and produced a kube config with that data), Headlamp will read those settings and
+try to use them for offering the effortless login to the cluster.
+
+Still, the kube config OIDC settings will not provide a OIDC callback URL, so make sure that your OIDC configuration for your cluster include Headlamp's OIDC callback in its redirect URIs. i.e. say you're using
+Dex for the OIDC connection and you have it already configured in your
+kube config, then be sure to add the `/oidc-callback` endpoint with Headlamp's the local address
+to Dex's `staticClient.redirectURIs`: `http://localhost:6644/oidc-callback`.

docs/installation/desktop/linux-installation.md

+---
+title: Linux Installation
+linktitle: Linux
+---
+
+Currently we ship a Linux desktop application as an AppImage file. So you
+can just run the application using the downloaded file.
+
+To download, choose the latest AppImage file from the [releases page](https://github.com/kinvolk/headlamp/releases).
+You can then run it by doing:
+
+```bash
+./Headlamp.AppImage
+```

docs/installation/desktop/mac-installation.md

+---
+title: Mac OS Installation
+linktitle: Mac OS
+---
+
+TBD

docs/installation/in-cluster.md

+---
+title: In-cluster Deployment
+weight: 10
+---
+
+A common use-case for any Kubernetes web UI is to deploy it in-cluster and
+set up an ingress server for having it available to users.
+
+We maintain a simple/vanilla [file](https://github.com/kinvolk/headlamp/blob/master/kubernetes-headlamp.yaml)
+for setting up a Headlamp deployment and service. Be sure to review it and change
+anything you need.
+
+If you're happy with the options in the this deployment file, and assuming
+you have a running Kubernetes cluster and your `kubeconfig` pointing to it,
+you can run:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/kinvolk/headlamp/master/kubernetes-headlamp.yaml
+```
+
+With this, the Headlamp service should be running, but you still need the
+ingress server as mentioned. We provide an example sample ingress yaml file
+for this purpose, but you have to manually replace the __URL__ placeholder
+with the desired URL (the ingress file also assumes that you have contour
+and a cert-manager set up, but if you don't then you'll just not have TLS).
+
+Assuming your URL is `headlamp.mydeployment.io`, getting the sample ingress
+file and changing the URL can quickly be done by:
+
+```bash
+curl -s https://raw.githubusercontent.com/kinvolk/headlamp/jrocha/wip/delme/kubernetes-headlamp-ingress-sample.yaml | sed -e s/__URL__/headlamp.mydeployment.io/ > headlamp-ingress.yaml
+```
+
+and with that, you'll have a configured ingress file, so verify it and apply it:
+```bash
+kubectl apply -f ./headlamp-ingress.yaml
+```
+
+## Accessing using OIDC
+
+Headlamp supports OIDC for cluster users to effortlessly log in.
+
+![screenshot the login dialog for a cluster](./oidc_button.png)
+
+For OIDC to be used, Headlamp needs to know how to configure it, so you have to provide the different OIDC-related arguments to Headlamp from your OIDC provider. Those are:
+
+ * the client ID: `-oidc-client-id`
+ * the client secret: `-oidc-client-secret`
+ * the issuer URL: `-oidc-idp-issuer-url`
+
+and you have to tell the OIDC provider about the callback URL, which in Headlamp it is your URL + the `/oidc-callback` path, e.g.:
+`https://YOUR_URL/oidc-callback`
+
+### Example: OIDC with Dex
+
+If you are using Dex and want to configure Headlamp to use it for OIDC,
+then you have to:
+
+  * Add the callback URL (e.g. `https://YOUR_URL/oidc-callback`) to Dex's `staticClient.redirectURIs`
+  * Set `-oidc-client-id` as Dex's `staticClient.id`
+  * Set `-oidc-client-secret` as Dex's `staticClient.secret`
+  * Set `-oidc-idp-issuer-url` as Dex's URL (same as in `--oidc-issuer-url` in the Kubernetes APIServer)

frontend/public/logo-light.svg

+<svg width="173" height="32" viewBox="0 0 173 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M40.65 15.9518V25.5807H36.1565V3.11328H40.65V12.1002H49.4764V3.11328H53.9699V25.5807H49.4764V15.9518H40.65Z" fill="#FFD31D"/>
+<path d="M70.8204 21.8254V25.5807H61.2237L57.5005 23.4303V11.5225L61.2237 9.37207H67.0973L70.8204 11.5225V19.1935H61.8977V21.8254H70.8204ZM61.8977 13.1273V15.8876H66.4233V13.1273H61.8977Z" fill="#FFD31D"/>
+<path d="M77.1114 25.7412L73.3882 23.5907V18.038L77.1114 15.8876H82.311V13.2878H74.993V9.53253H82.985L86.7082 11.683V25.7412H84.5898L82.311 24.4252L80.0321 25.7412H77.1114ZM77.7854 19.2577V22.0501H82.311V19.2577H77.7854Z" fill="#FFD31D"/>
+<path d="M93.6409 9.37206H97.8455L100.124 10.688V2.15039H104.522V25.7412H100.895L100.124 24.4252L97.8455 25.7412H93.6409L89.9177 23.5907V11.5225L93.6409 9.37206ZM100.124 21.9859V13.1273H94.3149V21.9859H100.124Z" fill="#FFD31D"/>
+<path d="M111.454 25.5807L107.731 23.4302V2.15039H112.128V21.8254H115.338V25.5807H111.454Z" fill="#FFD31D"/>
+<path d="M119.703 25.7412L115.98 23.5907V18.038L119.703 15.8876H124.903V13.2878H117.585V9.53253H125.577L129.3 11.683V25.7412H127.182L124.903 24.4252L122.624 25.7412H119.703ZM120.377 19.2577V22.0501H124.903V19.2577H120.377Z" fill="#FFD31D"/>
+<path d="M155.073 11.5225V25.5807H150.676V13.1273H145.99V25.5807H141.593V13.1273H136.907V25.5807H132.51V9.37207H136.136L136.907 10.688L139.186 9.37207H142.267L145.252 11.1053L148.269 9.37207H151.35L155.073 11.5225Z" fill="#FFD31D"/>
+<path d="M169.164 25.7412H164.959L162.68 24.4252V32H158.283V9.37207H161.91L162.68 10.688L164.959 9.37207H169.164L172.887 11.5225V23.5907L169.164 25.7412ZM162.68 13.1273V21.9859H168.49V13.1273H162.68Z" fill="#FFD31D"/>
+<path d="M7.39819 0H15.2618V3.11334L20.7021 5.13541V8.98696L22.1785 11.2658V17.9258L20.8144 20.2849L22.1785 24.5216L11.0893 28.2126L0.0802407 24.5216L1.38014 20.2849L0 17.9258V11.2658L1.74925 8.98696V5.13541L7.39819 3.11334V0Z" fill="#FFD31D"/>
+<path d="M11.1054 8.90674C13.962 8.90674 16.305 11.2658 16.289 14.0903C16.2729 16.9308 13.9299 19.2899 11.0894 19.2899C8.24888 19.3059 5.82561 16.8827 5.87375 14.0582C5.9219 11.1856 8.24888 8.90674 11.1054 8.90674Z" fill="black"/>
+</svg>