Merge branch 'docs/restructure' into 'master'

[![fsco.li/portal](./banner.png)](https://portal.fachschaft.cl.uni-heidelberg.de)

# Portal

# Portal: this service can fit so many services in it!

<div align="center">

Aren't you tired of having to remember shortlinks or URLs for all the services offered by the Fachschaft? Does it embarrass you to always ask about the agenda of a Fachschaftssitzung, because you never worked with a Taiga implementation? How was the shortlink to Sturacloud again? Are you overwhelmed by 19 (and counting, **fast**) different services offered by the Fachschaft, the Institute and the University?

<a href="https://fsco.li/portal">

<img src="./portal/static/img/portal.png" width="100px" /></a>

**Well, that is a thing of the past!** That's why we created Portal, a service-aggregating meta-service for over-zealous students like us, the FS Coli.

[**fsco.li/portal**](https://fsco.li/portal)

## What is Portal?

</div>

Portal is a service that aggregates all the services that the Fachschaft offers. It is a web application that is accessible via the URL [fsco.li/portal](https://portal.fachschaft.cl.uni-heidelberg.de). It is a service that is designed to be user-friendly and easy to use. It is a service that is designed to be accessible to all students, regardless of their technical background and cognitive abilities.

Maintainer: Jakob Moser <moser@cl.uni-heidelberg.de>

If you are a rather visual learner, we got you covered:

Portal is a web application providing links to the services the Fachschaft offers.

![This will make the purpose of portal clear once and for all.](info-4-devs/metaservice-badboy.png)

Aren't you tired of having to remember shortlinks or URLs for all the services offered by the Fachschaft? Does it embarrass you to always ask about the agenda of a Fachschaftssitzung, because you never got access to FS Coli Taiga? How was the shortlink to StuRaCloud again? Are you overwhelmed by 19 (and counting, _fast_) different services offered by the Fachschaft, the institute and the university?

## What can you do with Portal?

**Well, that is a thing of the past!** With Portal, all the services you need are now just a click away.

Most importantly, you can access all the services that the Fachschaft offers in one place. Also, Portal offers

## Which services does Portal offer?

-   a neat LDAP integration

-   a Taiga (fsco.li/todo) integration

-   even a f\*cking GitLab integration (we are so proud of this one)

-   an user-friendly interface

-   a responsive design (mostly)

- View lunch menu in the Zentralmensa, INF 304

  - By default, it shows today's menu. After 15:00, it shows tomorrow's menu.

- View agenda for Fachschaft meetings (after signing in with CL account)

- Quickly edit and download Fachschaft meeting minutes

- Mostly responsive design

- Hopefully user-friendly interface

- Links to services offered by Fachschaft, institute and university

# If you are a contributor...

----

## I want to setup portal on my local machine!

If you are a rather visual learner, we also got you covered:

First you gotta clone this repository.

We advise you to do this with Gitlabs VS Code integration, but you can also use the terminal.

```sh

git clone https://gitlab.cl.uni-heidelberg.de/Fachschaft/portal.git

```

Then you have two options:

### ...with docker

To run a flask shell inside the container:

```sh

sudo docker exec -it portal-app-1 flask shell

```

### ...without docker

```bash

# mkdir yourself into the portal directory

# Have pipenv (pip install pipenv) installed

pipenv install

pipenv shell

export FLASK_APP=portal

alembic upgrade head # to create (and update!) the database

flask run

```

Also, you have to set up the LDAP server in Flask. At the moment we are required to use a VPN or `lennonproxy` to access the LDAP server. The following command forwards the LDAP server to your local machine:

```sh

sudo ssh -D <your_forwarded_port> -p 80 <username>@lennon.cl.uni-heidelberg.de -L 636:ldap2:636

pipenv install

pipenv shell

export FLASK_APP=portal

alembic upgrade head # to create (and update!) the database

flask run

flask shell

```

```python

>>> from portal.model import *

>>> from portal import db

>>> l = ldapDirectory()

l = LdapDirectory()

l.url = "ldaps://ldap2.cl.uni-heidelberg.de"

l.base_dn= "ou=accounts,dc=cl,dc=uni-heidelberg,dc=de"

db.session.add(l)

db.session.commit()

exit()

```

The app should run without problems now.

Also, if you are using an Apple device, please deactivate the "AirPlay Receiver" as it might cause problems with the LDAP connection.

---

#### Important:

Alembic must always be up to date in order to update the database schema.

Please run `alembic upgrade head` after pulling changes from the repository.

---

## Compliance

### Formatting

We use [black](https://github.com/psf/black) as formatting tool.

Use `black .` to run the formatter.

### Static Type Checking

Run `mypy .` to let [mypy](https://www.mypy-lang.org/) validate the Python types.

## How to move around in this repo

## `/portal/`: Main Application

Here are all the important tech-stack related stuff and some Python files for Flask, contained in a cozy space

### `/portal/api/`: API Endpoints (Python)

Here you can find the API endpoints, written in Python

### `/portal/model`: database models (Python)

We use `SQLAlchemy` to interact with the database. The models are defined in this folder.

### `/portal/static`: CSS, JS, images, API documentation

This is giving the frontend some love and, more importantly, its purpose and functionality. The API documentation is also laying around here.

#### `/portal/static/css` (CSS, obviously)

Here you can find the CSS files for the frontend. The main CSS file is `main.css`.

#### `/portal/static/docs`

Here you can find the documentation for the API in its respective versions.

API specifications (`openapi-spec.yaml`) are written in OpenAPI 3.0.0 and are located in the `/api/{version}` folder.

#### `/portal/static/img`: Frag nicht, was für Bilder. Einfach Bilder. I won't translate this.

What did you expect?

#### `/portal/static/js`: JavaScript files

Lol, that should actually ![have its own README](info-4-devs/JS-README.md).

It contains all the JavaScript files that are responsible for the frontend interactions.

### `/portal/templates`

These are the HTML files that Flask renders. They are written in Jinja2, which is a template engine for Python.

### `.py`-files

-   `__init__.py`: Fortunately, explaining this was not a Prog2 exam question

-   `db_config.py`: [TODO] Have fun, Jakob. Database configuration (arcane magic).

-   `main.py`: The Flask server is in here

-   `problem_details.py`: RFC 7807-compliant problem details responses for the API.

![This will make the purpose of portal clear once and for all.](docs/img/metaservice-badboy.png)

# If you are a contributor...

> ⚡ **This project now uses [`uv`](https://github.com/astral-sh/uv) for dependency management.**  

> Install `uv` once using [`pipx`](https://pypa.github.io/pipx/):

```bash

pip install pipx

pipx install uv

```

## I want to setup portal on my local machine!

First you gotta clone this repository.

We advise you to do this with Gitlabs VS Code integration, but you can also use the terminal.

```sh

git clone https://gitlab.cl.uni-heidelberg.de/Fachschaft/portal.git

```

Then you have two options:

### ...with docker

To run a flask shell inside the container:

```sh

sudo docker exec -it portal-app-1 flask shell

```

### ...without docker

# Make sure you are in the `portal` directory

```bash

# mkdir yourself into the portal directory

# Technically optional: create a virtual environment manually

uv venv .venv

source .venv/bin/activate

uv pip sync

export FLASK_APP=portal

alembic upgrade head # to create (and update!) the database

flask run

```

Also, you have to set up the LDAP server in Flask. At the moment we are required to use a VPN or `lennonproxy` to access the LDAP server. The following command forwards the LDAP server to your local machine:

```sh

sudo ssh -D <your_forwarded_port> -p 80 <username>@lennon.cl.uni-heidelberg.de -L 636:ldap2:636

uv pip sync --dev

mkdir -p instance

touch instance/portal.db

export FLASK_APP=portal

alembic upgrade head # to create (and update!) the database

flask run

flask shell

```

```python

>>> from portal.model import *

>>> from portal import db

>>> l = ldapDirectory()

l = LdapDirectory()

l.url = "ldaps://ldap2.cl.uni-heidelberg.de"

l.base_dn= "ou=accounts,dc=cl,dc=uni-heidelberg,dc=de"

db.session.add(l)

db.session.commit()

exit()

```

The app should run without problems now.

Also, if you are using an Apple device, please deactivate the "AirPlay Receiver" as it might cause problems with the LDAP connection.

---

#### Important:

Alembic must always be up to date in order to update the database schema.

Please run `alembic upgrade head` after pulling changes from the repository.

---

## Compliance

### Formatting

We use [black](https://github.com/psf/black) as formatting tool.

Use `black .` to run the formatter.

### Static Type Checking

Run `mypy .` to let [mypy](https://www.mypy-lang.org/) validate the Python types.

## How to move around in this repo

## `/portal/`: Main Application

Here are all the important tech-stack related stuff and some Python files for Flask, contained in a cozy space

### `/portal/api/`: API Endpoints (Python)

Here you can find the API endpoints, written in Python

### `/portal/model`: database models (Python)

We use `SQLAlchemy` to interact with the database. The models are defined in this folder.

### `/portal/static`: CSS, JS, images, API documentation

This is giving the frontend some love and, more importantly, its purpose and functionality. The API documentation is also laying around here.

#### `/portal/static/css` (CSS, obviously)

Here you can find the CSS files for the frontend. The main CSS file is `main.css`.

#### `/portal/static/docs`

Here you can find the documentation for the API in its respective versions.

API specifications (`openapi-spec.yaml`) are written in OpenAPI 3.0.0 and are located in the `/api/{version}` folder.

#### `/portal/static/img`: Frag nicht, was für Bilder. Einfach Bilder. I won't translate this.

What did you expect?

#### `/portal/static/js`: JavaScript files

Lol, that should actually ![have its own README](./JS-README.md).

It contains all the JavaScript files that are responsible for the frontend interactions.

### `/portal/templates`

These are the HTML files that Flask renders. They are written in Jinja2, which is a template engine for Python.

### `.py`-files

- `__init__.py`: Fortunately, explaining this was not a Prog2 exam question

- `db_config.py`: [TODO] Have fun, Jakob. Database configuration (arcane magic).

- `main.py`: The Flask server is in here

- `problem_details.py`: RFC 7807-compliant problem details responses for the API.