Skip to content

Commit

Permalink
refactor: Merge user, admin and developer documentation
Browse files Browse the repository at this point in the history 
Previously, we had four different types of documentation:
- Developer documentation (exposed via Github pages)
- User documentation (exposed via individual instances)
- Admin documentation (partially in user docs, partially in README/CONRIBUTING)
- Getting started (in Github repository)

The number of different documentations led to increased maintainance effort.
Also, there was no single source of truth.

In this commit, all four documentation types are merged into one
`mkdocs` documentation. The documentation lived in the `docs` directory.
Switching between the different documentation types is now done via navigation tabs.
The new documentation is exposed via Github pages, making the user documentation
also available when no instance is running.

In addition to the merge, there were some other small changes:

- A new Makefile in the `docs` directory is added.
- The documentation is now part of the `dev` target in the Makefile.
  Run it via `make -j4 dev`.
- The code style development documentation was splitted into different
  backend and frontend code style pages.
- Most of the information in the `CONTRIBUTING.md` is moved to the
  development documentation.
- The development setup guide was simplified and and the focus is
  on getting everything running at the same time, not each service
  individually. All optional configuration options are moved to
  other parts of the documentation.
- The uninstall guide of the `README.md` is moved to the admin docs.
- A custom `style.css` is added to always show a scroll bar.
  It prevents vertical jumping when the scroll bar appears.
  • Loading branch information
@MoritzWeber0
MoritzWeber0 committed Oct 18, 2023
1 parent 685f7ca commit c865a83
Show file tree
Hide file tree
Showing 248 changed files with 693 additions and 757 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/docs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@ jobs:
python-version: "3.11"
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
working-directory: ./docs/development
working-directory: ./docs
251 changes: 3 additions & 248 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,252 +13,7 @@ environment. Be kind!
If you have questions, ideas or want to report a bug, feel free to [open an
issue](/../../issues). Or go ahead and [open a pull request](/../../pulls) to contribute
code. In order to reduce the burden on our maintainers, please make sure that
your code follows our style guidelines outlined below.
your code follows our style guidelines.

## General

This project consists of several services. Here is the architecture of the services:
![Capella Collab Manager architecture](docs/architecture.png)

To get an overview of the services, it is also worth taking a look at the Helm Chart,
which can be found in the `helm` folder.

We use REST APIs for the communication between frontend and backend.
Please follow the [RESTful web API design best practises](https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design).

We recommend to get started with the [local k8d deployment](README.md).

<!-- prettier-ignore -->
By default, the services run on the following ports when using the instructions below:
| Port | Service |
|-------|---------------------|
| 8080 | k3d deployment |
| 12345 | k3d registry |
| 4200 | frontend |
| 8000 | backend |
| 8081 | t4c-server mock |
| 8082 | license-server mock |
| 8083 | oauth-mock |

## Git

The commit messages have to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification) specification.

In general, we use pre-commit hooks to enforce coding standards.
To setup the pre-commit hooks, please run the following commands:

```zsh
pip install -U pip pre-commit
pre-commit install -t pre-commit -t commit-msg
```

## Capella Docker images

Please follow the [README of the Capella Docker images repository](/../../../capella-dockerimages/blob/main/README.md).
When all files are in the right place, you can execute the following command to build
and push the Docker images.

```sh
make capella-dockerimages
```

## OAuth Server

We use OAuth2 as authentication protocol for our application. Therefore we need an
OAuth2 server. For local development, we have an OAuth mock that needs to be started
first.

Do not use the OAuth mock in production!

First of all, navigate to the `mocks/oauth` directory.

1. Run the OAuth2-Mock-Server with:

```sh
make start
```

2. Verify that the server runs, e.g., by navigating to
[Well Known](http://localhost:8083/default/.well-known/openid-configuration)

## Backend

Requirements:

- `python` and `pip`
- `docker`
- `make`

Run the following steps:

1. In the project's root directory you must create a local k3d cluster by running

```sh
make create-cluster
```

1. In order to use Guacamole, the cluster must be deployed:

```sh
make deploy
```

1. Navigate to the `backend` directory of your cloned repository.
1. We recommend that you develop inside of a virtual environment. To set it up,
run the following commands:

```sh
python -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools
pip install -e '.[dev]'
```

1. The backend uses various configuration settings. You can find them in the `config`
directory.
Please copy the file `config_template.yaml` to `config.yaml` and adjust the values.

_Hint_: If you already have the k8d cluster running and if you have the
application deployed, then no configuration values need to be adjusted.

_Hint_: You can run `python -m capellacollab.config.diff` after each update to check if your config is up to date.

1. To begin the development a PostgreSQL database is required. To run the database and
start the backend run:

```sh
make dev
```

1. You should see it running on port 8000.

- [Healthcheck](http://localhost:8000/healthcheck)
- [Documentation](http://localhost:8000/docs)

We additionally recommend that you set up your editor / IDE as follows.

- Indent with 4 spaces per level of indentation
- Maximum line length of 79 (add a ruler / thin line / highlighting / ...)
- Set up the editor to run `black`, `pylint`, `mypy` and `isort` when saving.

### Create database migrations scripts

To create an upgrade script automatically (this will compare the current database state
with the models):

```sh
alembic revision --autogenerate -m "Commit message"
```

## Authentication without application frontend

Request the `auth_url`

```sh
curl -X 'GET' \
'http://127.0.0.1:8000/api/v1/authentication/' \
-H 'accept: application/json'
```

Opening the `auth_url` in a browser leads you to a "Mock OAuth2 Server Sign-in" page.

Login as user `admin` to be redirected to a page that is reachable when the frontend
runs. Anyway the redirect URL in the browser's address input field contains two
parameters `code` and `status`.

Example:

<pre>
http://localhost:4200/oauth2/callback?...
...code=<span style="color:green">MREy4raZT9JqaYn_50yJraU4zkclGQbNcbudW404ekc</span>...
...&state=<span style="color:green">r7huaqqdDBWTb8x4gUDIpt36izM0Au</span>
</pre>

One must copy these parameters and post them via a second request returning an access
token:

```sh
curl -X 'POST' \
'http://127.0.0.1:8000/api/v1/authentication/tokens' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"code": "MREy4raZT9JqaYn_50yJraU4zkclGQbNcbudW404ekc",
"state": "r7huaqqdDBWTb8x4gUDIpt36izM0Au"
}'
```

To send a request using that token you may want to request the list of projects:

```sh
curl -X 'GET' \
'http://127.0.0.1:8000/api/v1/projects/' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'
```

whereby `<TOKEN>` must be replaced by the token you received above.

Using the Swagger UI one can click on the lock symbols to enter the access token.

## Frontend

Requirements:

- Node.js 18
- `npm` package manager
- [Angular CLI](https://angular.io/cli#installing-angular-cli)
- `make`

Run the following steps:

1. Navigate to the `frontend` folder
1. Install dependencies via `npm install`
1. Optional: If you like to use your custom favicon, please copy it to `src/favicon.ico`
1. Optional: If you like to use your custom theme, replace the file `src/custom-theme.scss`.
You can generate custom themes [here](http://mcg.mbitson.com/)
1. Run the frontend with:

```sh
make dev
```

1. You should see the frontend running on port 4200.

We additionally recommend that you set up your editor / IDE as follows.

- Set up the editor to run [prettier](https://prettier.io/) when saving.

## User documentation

Requirements:

- `python` + `pip`

Run the following steps:

1. Navigate to the `docs/user` directory of your cloned repository.
2. We recommend that you develop inside of a virtual environment. To set it up,
run the following commands:

```zsh
python -m venv .venv
source .venv/bin/activate
pip install -U pip setuptools
```

3. Install MkDocs Material:

```zsh
pip install mkdocs-material
```

4. Serve the docs:

```zsh
mkdocs serve
```

## Code style

You can find our code style rules [here](https://dsd-dbs.github.io/capella-collab-manager/code-style/)
We provide a developer documentation. There you will also find information
on how to set up a local environment: [Developer Documentation](https://dsd-dbs.github.io/capella-collab-manager/development/)
7 changes: 5 additions & 2 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -157,8 +157,8 @@ provision-guacamole:
kubectl exec -i --context k3d-$(CLUSTER_NAME) --namespace $(NAMESPACE) deployment/$(RELEASE)-guacamole-postgres -- psql -U guacamole guacamole
@echo "Guacamole database initialized sucessfully.";

# Execute with `make -j3 dev`
dev: dev-oauth-mock dev-frontend dev-backend
# Execute with `make -j4 dev`
dev: dev-oauth-mock dev-frontend dev-backend dev-docs

dev-frontend:
$(MAKE) -C frontend dev
Expand All @@ -169,6 +169,9 @@ dev-backend:
dev-oauth-mock:
$(MAKE) -C mocks/oauth start

dev-docs:
$(MAKE) -C docs serve

backend-logs:
kubectl logs -f -n $(NAMESPACE) -l id=$(RELEASE)-deployment-backend

Expand Down
27 changes: 3 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -144,39 +144,18 @@ running in a few minutes.

### Deployment

You can find the installation guide for deployment in the [general documentation](https://capella-collaboration-manager.readthedocs.io/en/latest/installation/).

### Uninstall the environment

1. If you want to uninstall the management portal, you can run the following comment:

```sh
helm uninstall production -n <namespace> helm
```

1. The previous command doesn't clean the sessions namespace.
Please clean it manually by running (this does also remove all persistent workspaces!):

```zsh
kubectl -n <sessions-namespace> delete all --all
```

or just delete the namespace:

```zsh
kubectl delete namespace <sessions-namespace>
```
You can find the installation guide for the deployment in the [general documentation](https://capella-collaboration-manager.readthedocs.io/en/latest/installation/).

## How it works

![Capella Collab Manager architecture](docs/architecture.png)

The Capella Collaboration Manager consists of a couple of components:

- A frontend - what you see in the browser
- A backend service - for managing projects, users and sessions
- [Guacamole](https://guacamole.apache.org/), to expose the sessions via the browser
- Databases, for state persistence
- Prometheus for session monitoring
- Grafana Loki for logs management

External software can also be linked. These parts can be installed separately:

Expand Down
13 changes: 0 additions & 13 deletions ci-templates/README.md
View file

This file was deleted.

Loading

0 comments on commit c865a83

Please sign in to comment.