refactor: Merge user, admin and developer documentation

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.
DSD-DBS · Oct 18, 2023 · cbc203f · cbc203f
1 parent 74e2137
commit cbc203f
Show file tree

Hide file tree

Showing 245 changed files with 471 additions and 546 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -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/)
diff --git a/Makefile b/Makefile
@@ -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
@@ -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
 

diff --git a/README.md b/README.md
@@ -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:
 

diff --git a/capella-dockerimages b/capella-dockerimages
diff --git a/docs/user/.dockerignore → docs/.dockerignore b/docs/user/.dockerignore → docs/.dockerignore
diff --git a/docs/user/.gitignore → docs/.gitignore b/docs/user/.gitignore → docs/.gitignore
diff --git a/docs/user/.markdownlint.yaml → docs/.markdownlint.yaml b/docs/user/.markdownlint.yaml → docs/.markdownlint.yaml
diff --git a/docs/user/.prettierrc.yaml → docs/.prettierrc.yaml b/docs/user/.prettierrc.yaml → docs/.prettierrc.yaml
diff --git a/docs/user/.readthedocs.yaml → docs/.readthedocs.yaml b/docs/user/.readthedocs.yaml → docs/.readthedocs.yaml
diff --git a/docs/user/Dockerfile → docs/Dockerfile b/docs/user/Dockerfile → docs/Dockerfile
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,6 @@
+install:
+	python -m venv .venv
+	.venv/bin/pip install -r requirements.txt
+
+serve:
+	.venv/bin/mkdocs serve
diff --git a/docs/architecture.png b/docs/architecture.png
diff --git a/docs/architecture.png.license b/docs/architecture.png.license
diff --git a/docs/development/docs/index.md b/docs/development/docs/index.md
diff --git a/docs/development/docs/release-notes.md b/docs/development/docs/release-notes.md
+15 −0		.github/workflows/deploy-docker-images.yml
+0 −25		.github/workflows/pre-commit.yml
+8 −0		.hadolint.yaml
+5 −1		.pre-commit-config.yaml
+17 −0		LICENSES/MIT.txt
+35 −16		Makefile
+33 −4		base/Dockerfile
+8 −0		base/hooks/+pre-commit-and-lfs.sh
+5 −0		base/hooks/+pre-commit-only.sh
+31 −0		base/hooks/+pre-commit.sh
+1 −1		builder/Dockerfile
+17 −7		capella/Dockerfile
+33 −6		capella/setup_workspace.py
+1 −1		ci-templates/gitlab/diagram-cache.yml
+3 −1		ci-templates/gitlab/model-validation.yml
+ −		docs/docs/git-hooks/egit-failed-git-hook.png
+2 −0		docs/docs/git-hooks/egit-failed-git-hook.png.license
+55 −0		docs/docs/git-hooks/git-hooks.md
+1 −0		docs/mkdocs.yml
+10 −11		ease/Dockerfile
+6 −2		ease/debug/Dockerfile
+4 −1		eclipse/Dockerfile
+8 −5		jupyter-notebook/Dockerfile
+9 −2		jupyter-notebook/docker-entrypoint.sh
+5 −1		papyrus/Dockerfile
+1 −1		readonly/Dockerfile
+6 −2		readonly/startup.sh
+4 −4		remote/Dockerfile
+9 −6		remote/startup.sh
+12 −4		t4c/Dockerfile
+24 −13		t4c/backup.py
+63 −48		tests/conftest.py
+8 −4		tests/local-git-server/Dockerfile