Skip to content

Commit da1c87e

Browse files
joaquimrochajoaquimrocha
authored
Merge pull request #315 from kinvolk/improve_docs
Improve docs
2 parents f3800e1 + 3b0bd2c commit da1c87e

4 files changed

Lines changed: 110 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,22 +37,21 @@ the [Omaha](https://code.google.com/p/omaha/) protocol, with special functionali
3737

3838
Please report any issues in [here](https://github.com/kinvolk/nebraska/issues).
3939

40-
41-
## Managing Updates
42-
43-
Read the docs on [how to manage updates](./docs/managing-updates.md).
44-
4540
## Code of Conduct
4641

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

4944
## Contributing
5045

51-
If you want to start contributing to Nebraska, please check out the [contributing](./docs/contributing.md) documentation.
46+
If you want to start contributing to Nebraska, please check out the [contributing](https://kinvolk.io/docs/nebraska/latest/contributing/) documentation.
47+
48+
### Development
49+
50+
For a quickstart on setting up a development environment, please check the [development documentation](https://kinvolk.io/docs/nebraska/latest/development/).
5251

5352
### User Access
5453

55-
For instructions on how to set up user access, please check the [authorization documentation](./docs/authorization.md).
54+
For instructions on how to set up user access, please check the [authorization documentation](https://kinvolk.io/docs/nebraska/latest/authorization/).
5655

5756
## License
5857

‎docs/authorization.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: Nebraska Authorization
2+
title: Deployment & Authorization
33
weight: 10
44
---
55

6-
Nebraska uses either a noop authentication, or OAuth or Bearer tokens
6+
Nebraska uses either a noop authentication, OAuth or Bearer tokens
77
to authenticate and authorize users. Currently, only GitHub is
88
supported as an OAuth authentication backend. [GitHub personal access
99
tokens](https://github.com/settings/tokens) can be used as bearer
@@ -29,7 +29,7 @@ the `postgres` container as follows:
2929

3030
# Deploying Nebraska for testing on local computer (noop authentication)
3131

32-
- Go to the nebraska project directory and run `make all`
32+
- Go to the nebraska project directory and run `make`
3333

3434
- Start the database (see the section above if you need a quick setup).
3535

‎docs/contributing.md‎

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,53 @@
11
---
2-
title: Contributing
3-
weight: 10
2+
title: Contribution Guidelines
3+
linktitle: Contributing
44
---
55

6-
Nebraska is an Open Source project and contributions are welcome. It is usually a good idea to discuss new features or major changes before submitting any code. For doing that, please file a new [issue](https://github.com/Nebraska/Nebraska/issues).
6+
This section has information on how to contribute to Nebraska. It assumes you have cloned
7+
this repository (or your own Github fork).
78

8-
To build the whole project (backend + frontend), you can run:
9+
Any contributions to the project are accepted under the terms of the project's
10+
license ([AGPL v3](../LICENSE)).
911

10-
make
12+
## Code of Conduct
1113

12-
Below you will find some introductory notes that should point you in the right direction to start playing with the Nebraska source code.
14+
Please refer to the Kinvolk [Code of Conduct](https://github.com/kinvolk/contribution/blob/master/CODE_OF_CONDUCT.md).
1315

14-
## Backend
16+
## Development practices
1517

16-
The Nebraska backend is written in Go. The backend source code is structured as follows:
18+
The Nebraska 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.
1722

18-
- **`pkg/api`**: provides functionality to do CRUD operations on all elements found in Nebraska (applications, groups, channels, packages, etc), abstracting the rest of the components from the underlying datastore (PostgreSQL). It also controls the groups' roll-out policy logic and the instances/events registration.
23+
## Filing an issue or feature request
1924

20-
- **`pkg/omaha`**: provides functionality to validate, handle, process and reply to Omaha updates and events requests received from the Omaha clients. It relies on the `api` package to get update packages, store events, or register instances when needed.
25+
Please use the [project's issue tracker](https://github.com/kinvolk/nebraska/issues) for filing any bugs you find or features
26+
you think are useful.
2127

22-
- **`pkg/syncer`**: provides some functionality to synchronize packages available in the official Flatcar Container Linux channels, storing the references to them in your Nebraska datastore and even downloading packages payloads when configured to do so. It's basically in charge of keeping up to date your the Flatcar Container Linux application in your Nebraska installation.
28+
### Complex contributions
2329

24-
- **`cmd/nebraska`**: is the main backend process, exposing the functionality described above in the different packages through its http server. It provides several http endpoints used to drive most of the functionality of the dashboard as well as handling the Omaha updates and events requests received from your servers and applications.
30+
If you have a complex contribution in mind (meaning changes in the architecture
31+
or a lot of LOC changed), it is advisable to first file a Github issue and
32+
discuss the implementation with the project's maintainers.
2533

26-
- **`cmd/initdb`**: is just a helper to reset your database, and causing the migrations to be re-run. `nebraska` will apply all database migrations automatically, so this process should only be used to wipe out all your data and start from a clean state (you should probably never need it).
34+
## Coding style
2735

28-
To build the backend you can run:
36+
The coding style for `backend` and `frontend` should be consistent.
37+
For helping and verifying that, we have go and js linters.
2938

30-
make backend
39+
The `backend` linter runs automatically when using the `make backend`
40+
command.
41+
For linting the `frontend`, use `make frontend-lint`.
3142

32-
### Backend database
43+
The linters are also run in the CI system, so any PRs you create will be
44+
tested for compliance with the coding style.
3345

34-
Nebraska uses `PostgreSQL`. You can install it locally or use the docker image available in the quay.io registry (`quay.io/flatcar/nebraska-postgres`). If you don't use the docker image provided, you'll have to set up the database yourself. By default Nebraska uses a database with the name `nebraska`, and `nebraska_tests`
35-
for the tests, respectively. For the main database, the full URL (with a different database name if desired) can be overridden by the environment variable
36-
`NEBRASKA_DB_URL`.
46+
To speed up a review from the project's maintainers, please make sure that
47+
the CI checks are passing for your PR.
3748

38-
Note: the timezone for the Nebraska database is expected to be UTC (`set timezone = 'utc';`).
49+
## Commit guidelines
3950

40-
## Frontend
41-
42-
The frontend side of Nebraska (dashboard) is a web application built using `react` and `material-ui`.
43-
44-
To build the webapp you have to install `node.js`. After that, you can build it using:
45-
46-
make frontend
47-
48-
It is very useful to be able to quickly build the frontend while changing it during development, and for that you can use the following make target:
49-
50-
make frontend-watch
51+
For the general guidelines on making PRs/commits easier to review, please check
52+
out Kinvolk's
53+
[contribution guidelines on git](https://github.com/kinvolk/contribution/tree/master/topics/git.md).

‎docs/development.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Development
3+
weight: 20
4+
---
5+
6+
This section shows how to set up a development environment for Nebraska.
7+
Be also sure to read the [contributing](./contributing) section for the
8+
general guidelines when contributing to Nebraska.
9+
10+
Nebraska needs a running `PostgresSQL` database. Apart from that, the
11+
recommended way to work on it, is to run the backend with the `noop`
12+
authentication backend, and the frontend in a "watch" mode (where it
13+
auto-refreshes when there are changes to the frontend).
14+
15+
# Preparing the Database
16+
17+
Nebraska uses the `PostgreSQL` database, and expects the used
18+
database to be set to the UTC timezone.
19+
20+
By default Nebraska uses a database with the name `nebraska`, and
21+
`nebraska_tests` for the tests, respectively. For the main database, the full
22+
URL (with a different database name if desired) can be overridden by the
23+
environment variable `NEBRASKA_DB_URL`.
24+
25+
For a quick setup of `PostgreSQL` for Nebraska's development, you can use
26+
the `postgres` container as follows:
27+
28+
- Start `Postgres`:
29+
- `docker run --rm -d --name nebraska-postgres-dev -p 5432:5432 -e POSTGRES_PASSWORD=nebraska postgres`
30+
31+
- Create the database for Nebraska (by default it is `nebraska`):
32+
- `psql postgres://postgres:nebraska@localhost:5432/postgres -c 'create database nebraska;'`
33+
34+
- Set the timezone to Nebraska's database:
35+
- `psql postgres://postgres:nebraska@localhost:5432/nebraska -c 'set timezone = "utc";'`
36+
37+
# Development Quickstart
38+
39+
- Go to the Nebraska project directory and run `make`
40+
41+
- Run the backend (with the `noop` authentication): `make run-backend`
42+
43+
- Then, in a different terminal tab/window, run the frontend: `make run-frontend`
44+
45+
Any changes to the backend means that the `make run-backend` command should be
46+
run again. Changes to the frontend should be automatically re-built and the
47+
opened browser page should automatically refresh.
48+
49+
# Development Concepts
50+
51+
## Frontend
52+
53+
The [frontend](https://github.com/kinvolk/nebraska/frontend) side of Nebraska is a web application built using `React` and `Material-UI`.
54+
55+
## Backend
56+
57+
The Nebraska backend is written in Go. The backend source code is structured as follows:
58+
59+
- **`pkg/api`**: provides functionality to do CRUD operations on all elements found in Nebraska (applications, groups, channels, packages, etc), abstracting the rest of the components from the underlying datastore (PostgreSQL). It also controls the groups' roll-out policy logic and the instances/events registration.
60+
61+
- **`pkg/omaha`**: provides functionality to validate, handle, process and reply to Omaha updates and events requests received from the Omaha clients. It relies on the `api` package to get update packages, store events, or register instances when needed.
62+
63+
- **`pkg/syncer`**: provides some functionality to synchronize packages available in the official Flatcar Container Linux channels, storing the references to them in your Nebraska datastore and even downloading packages payloads when configured to do so. It's basically in charge of keeping up to date your the Flatcar Container Linux application in your Nebraska installation.
64+
65+
- **`cmd/nebraska`**: is the main backend process, exposing the functionality described above in the different packages through its http server. It provides several http endpoints used to drive most of the functionality of the dashboard as well as handling the Omaha updates and events requests received from your servers and applications.
66+
67+
- **`cmd/initdb`**: is just a helper to reset your database, and causing the migrations to be re-run. `nebraska` will apply all database migrations automatically, so this process should only be used to wipe out all your data and start from a clean state (you should probably never need it).

0 commit comments

Comments
 (0)