Skip to content

Commit e2970f5

Browse files
joaquimrochajoaquimrocha
authored
Merge pull request #109 from kinvolk/jrocha/wip/new_docs
Add new README and docs
2 parents 0ddd312 + c0ad540 commit e2970f5

20 files changed

+676
-71
lines changed

Diff for: ‎README.md

+38-17
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,50 @@
1-
# Headlamp
1+
# Headlamp <img align="right" width=384 src="docs/headlamp_light.svg">
22

3-
An easy-to-use and versatile dashboard for Kubernetes.
3+
Headlamp is an easy-to-use and extensible Kubernetes web UI.
44

5-
*⚠️ IMPORTANT:* This is an early version of Headlamp, which is under active
6-
development and thus subject to frequent and, potentially, breaking changes.
7-
8-
## Introduction / Demo
9-
10-
Here is an introduction video with the motivation for creating headlamp
11-
and a brief demo of it.
5+
Headlamp was created to be a Kubernetes web UI that has the traditional functionality of other
6+
web UIs/dashboards available (i.e. to list and view resources) as well as other features.
127

138
<div align="center">
14-
<a href="https://www.youtube.com/watch?v=cZEcdTOwV-A&feature=youtu.be&t=21609" target="_blank">
15-
<img src="https://raw.githubusercontent.com/kinvolk/headlamp/media/screenshots/yt_intro.png" width="400px">
16-
</a>
9+
<img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/videos/headlamp_quick_run.gif" width="80%">
1710
</div>
1811

1912
## Features
2013

21-
* Vendor independent / Generic
22-
* Common ops for Kubernetes clusters
14+
* Vendor independent / generic Kubernetes UI
15+
* UI controls reflecting user roles (no deletion/update if not allowed)
2316
* Multi-cluster
24-
* Extensible
25-
* Clean / modern UI
26-
* Read-write (actions based on permissions)
17+
* Extensible through plugins
18+
* Clean & modern UI
19+
* Works in-cluster, or locally as a desktop app
20+
* Cancellable creation/update/deletion operations
21+
* Logs, exec, and resource editor with documentation
22+
* Read-write / interactive (actions based on permissions)
23+
24+
## Screenshots
25+
26+
<table>
27+
<tr>
28+
<td width="33%"><img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/screenshots/cluster_overview.png"></td>
29+
<td width="33%"><img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/screenshots/cluster_chooser.png"></td>
30+
</tr>
31+
<tr>
32+
<td width="33%"><img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/screenshots/nodes.png"></td>
33+
<td width="33%"><img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/screenshots/resource_edition.png"></td>
34+
</tr>
35+
<tr>
36+
<td width="33%"><img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/screenshots/editor_documentation.png"></td>
37+
<td width="33%"><img src="https://raw.githubusercontent.com/kinvolk/headlamp/screenshots/screenshots/terminal.png"></td>
38+
</tr>
39+
</table>
40+
41+
## Quickstart
42+
43+
If you want to deploy Headlamp in your cluster, check out the instructions on running it [in-cluster](./docs/installation/in-cluster.md).
44+
45+
If you have a kube config already, you can quickly try Headlamp locally as a
46+
[desktop application](./docs/installation/desktop/_index.md). **Make sure** you have a kube config
47+
set up with your favorite clusters and in the default path so Headlamp can use it.
2748

2849
## Get involved
2950

Diff for: ‎app/package-lock.json

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

Diff for: ‎app/package.json

+18-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "headlamp",
3-
"version": "1.0.0",
3+
"version": "0.1.0",
44
"description": "",
55
"main": "electron/main.js",
66
"homepage": ".",
@@ -20,12 +20,28 @@
2020
},
2121
"linux": {
2222
"target": [
23-
"AppImage"
23+
"AppImage",
24+
"tar.gz"
2425
],
2526
"executableName": "headlamp",
2627
"artifactName": "${productName}.${ext}",
2728
"maintainer": "Kinvolk <[email protected]>"
2829
},
30+
"mac": {
31+
"target": [
32+
"dmg",
33+
"tar.gz",
34+
"zip",
35+
"pkg"
36+
]
37+
},
38+
"win": {
39+
"target": [
40+
"zip",
41+
"msi",
42+
"nsis"
43+
]
44+
},
2945
"files": [
3046
"build/**/*",
3147
"../frontend/node_modules/**/*",

Diff for: ‎docs/_index.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Headlamp
3+
---
4+
5+
Headlamp is an easy-to-use and extensible Kubernetes web UI.
6+
7+
Headlamp was created to be a Kubernetes web UI that has the traditional functionality of other
8+
web UIs/dashboards available (i.e. to list and view resources) as well as other features.
9+
10+
Headlamp can be used in-cluster, where it's accessed through a web browser,
11+
or as a desktop application (using the information defined in the user's
12+
kubeconfig).

Diff for: ‎docs/contributing.md

+14-51
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1-
# Contribution Guidelines
1+
---
2+
title: Contribution Guidelines
3+
linktitle: Contributing
4+
---
25

3-
This section serves as an introduction on how to contribute to Headlamp; getting started, development practices, filing issues, etc..
4-
It assumes you have cloned this repository (or your own Github fork).
6+
This section has information on how to contribute to Headlamp. It assumes you have cloned
7+
this repository (or your own Github fork).
58

69
Any contributions to the project are accepted under the terms of the project's
710
license ([Apache 2.0](../LICENSE)).
@@ -10,6 +13,13 @@ license ([Apache 2.0](../LICENSE)).
1013

1114
Please refer to the Kinvolk [Code of Conduct](https://github.com/kinvolk/contribution/blob/master/CODE_OF_CONDUCT.md).
1215

16+
## Development practices
17+
18+
The Headlamp project follows the [Kinvolk Contribution Guidelines](https://github.com/kinvolk/contribution)
19+
which promotes good and consistent contribution practises across Kinvolk's
20+
projects. Before start contributing, and in addition to this section, please
21+
read those guidelines.
22+
1323
## Filing an issue or feature request
1424

1525
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
2131
or a lot of LOC changed), it is advisable to first file a Github issue and
2232
discuss the implementation with the project's maintainers.
2333

24-
## Build the code
25-
26-
Headlamp is composed by a `backend` and a `frontend`.
27-
28-
You can build both the `backend` and `frontend` by running.
29-
30-
```bash
31-
make
32-
```
33-
34-
Or individually:
35-
36-
```bash
37-
make backend
38-
```
39-
40-
and
41-
42-
```bash
43-
make frontend
44-
```
45-
46-
## Run the code
47-
48-
The quickest way to get the `backend` and `frontend` running for development is
49-
the following (respectively):
50-
51-
```bash
52-
make run-backend
53-
```
54-
55-
and in a different terminal instance:
56-
57-
```bash
58-
make run-frontend
59-
```
60-
61-
## Build a Docker image
62-
63-
The following command builds a Docker image for Headlamp from the current
64-
source. It will run the `frontend` from a `backend`'s static server, and
65-
options can be appended to the main command as arguments.
66-
67-
```bash
68-
make image
69-
```
70-
71-
### Coding style
34+
## Coding style
7235

7336
The coding style for `backend` and `frontend` should be consistent.
7437
For helping and verifying that, we have go and js linters.

Diff for: ‎docs/development/_index.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Development
3+
---
4+
5+
This is a quickstart guide for building and running Headlamp for development.
6+
7+
Please make sure you read the [Contribution Guidelines](../contributing.md) as well
8+
before starting to contribute to the project.
9+
10+
## Build the code
11+
12+
Headlamp is composed by a `backend` and a `frontend`.
13+
14+
You can build both the `backend` and `frontend` by running.
15+
16+
```bash
17+
make
18+
```
19+
20+
Or individually:
21+
22+
```bash
23+
make backend
24+
```
25+
26+
and
27+
28+
```bash
29+
make frontend
30+
```
31+
32+
## Run the code
33+
34+
The quickest way to get the `backend` and `frontend` running for development is
35+
the following (respectively):
36+
37+
```bash
38+
make run-backend
39+
```
40+
41+
and in a different terminal instance:
42+
43+
```bash
44+
make run-frontend
45+
```
46+
47+
## Build a Docker image
48+
49+
The following command builds a Docker image for Headlamp from the current
50+
source. It will run the `frontend` from a `backend`'s static server, and
51+
options can be appended to the main command as arguments.
52+
53+
```bash
54+
make image
55+
```
56+
57+
### Shipping plugins in the Docker image
58+
59+
Since the Headlamp server has an option (`-plugins-dir`) for indicating where to find any plugins,
60+
a deployment of Headlamp using the Docker image can mount a plugins folder
61+
and point to it by using the mentioned option.
62+
63+
An alternative is to build an image that ships some plugins in it. For that,
64+
just create a plugins folder in the Headlamp project directory as the Dockerfile
65+
will include it and point to it by default.

Diff for: ‎docs/development/backend.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Backend
3+
weight: 5
4+
---
5+
6+
Headlamp's backend is written in Go and is in charge of redirecting the
7+
client requests to the right clusters, as well as to return any available
8+
plugins for the client to use.
9+
10+
The backend most basic and essential function is to read the cluster information
11+
from the given configuration, and set up proxies to the defined clusters as
12+
well as endpoints to them. This means that instead of having a set of
13+
endpoints related to the functionality available to the client, it simply
14+
redirects the requests to the defined proxies.
15+
16+
## Building and running
17+
18+
The backend (Headlamp's server) can be quickly built using:
19+
20+
```bash
21+
make backend
22+
```
23+
24+
Once built, it can be run in development mode (insecure / don't use in production) using:
25+
26+
27+
```bash
28+
make run-backend
29+
```

Diff for: ‎docs/development/frontend.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Frontend
3+
weight: 5
4+
---
5+
6+
The frontend is written in Typescript and React, as well as a few other important modules like:
7+
* Material UI
8+
* React Router
9+
* Redux
10+
* Redux Sagas
11+
12+
## Building and running
13+
14+
The frontend can be quickly built using:
15+
16+
```bash
17+
make frontend
18+
```
19+
20+
Once built, it can be run in development mode (auto-refresh) using:
21+
22+
23+
```bash
24+
make run-frontend
25+
```
26+
27+
This command leverages the `create-react-app`'s start script that launches
28+
a development server for the frontend (by default at `localhost:3000`).

Diff for: ‎docs/development/plugins/_index.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Plugins
3+
linkTitle: Plugins
4+
---
5+
6+
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.
7+
8+
# Developing Plugins
9+
10+
Plugins are supposed to be built and shipped out-of-tree, i.e. instead of managing the plugins'
11+
code within the Headlamp project or a Headlamp fork (which would require
12+
always rebuilding/maintaining Headlamp when changing a plugin), they're
13+
supposed to be built outside of the project and just pointed to by the
14+
Headlamp's server.
15+
16+
*⚠️ IMPORTANT FOR DEVS:* The plugins system and plugins lib is still in the process of being
17+
consolidated. This means that 1) it's subject to change, 2) you are very
18+
welcome to contribute to it with different use cases and/or development.

0 commit comments

Comments
 (0)