Merge branch 'docs/improve-docs' into 'master'

# Contributing

## How to move around in this repo

To find out where your changes should go to implement a particular feature or fix a bug, read the architecture documentation. This document will also link to further documentation and code as needed.

* [Architecture documentation](./docs/architecture.md)

## Formatting

We use [Ruff](https://astral.sh/ruff) as a formatting tool. You can run it using `uv`:

```bash

uv run ruff format .

```

**Your code will only be merged to `master` if it is correctly formatted.** We recommend formatting before every commit.

## Type Checking

We use [mypy](https://www.mypy-lang.org/) to validate our type hints. You can run it using `uv`:

```bash

uv run mypy .

```

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

## Which services does Portal offer?

## Features

- View lunch menu in the Zentralmensa, INF 304

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

- Hopefully user-friendly interface

- Links to services offered by Fachschaft, institute and university

----

## Contributing

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

See the [Contributing Guide](./CONTRIBUTING.md) for more details on how to contribute.

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

## Run Portal locally

Install necessary dependencies:

* [Git](https://git-scm.com/)

* [uv](https://docs.astral.sh/uv/#installation)

On the pool computers, Git is already installed, and uv can be installed with:

```sh

curl -LsSf https://astral.sh/uv/install.sh | sh

source $HOME/.local/bin/env

```

Then, clone the repository. You can do this using the Git integration of VS Code, or via the terminal:

```sh

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

```

Then, run:

```sh

cd portal

mkdir instance # only necessary at first start

export FLASK_APP=portal

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

uv run flask run

```

You can now access Portal at https://localhost:5000

> [!note]

> After pulling changes from the repository, please run:

>

> ```

> uv run alembic upgrade head

> ```

>

> This is because the database schema might have changed online. Your local database must be upgraded to the latest schema to run the latest code.

### Dockerized alternative

If you have Docker installed and enabled, you can also skip all of the instructions above:

```sh

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

cd portal

mkdir instance

sudo docker compose -f docker-compose.dev.yml up

```

## Flask shell

Sometimes, you need to enter a “Flask shell”, to change internal configuration. This works like this:

```bash

uv run flask shell

```

If you're using Docker, it works like this:

```bash

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

```

## Configure

### LDAP server

To use the CL account login feature, you need to configure an `LdapDirectory`. 

Open a Flask shell (see above), and then execute:

```python

>>> l = LdapDirectory(url="ldaps://ldap2.cl.uni-heidelberg.de", base_dn="ou=accounts,dc=cl,dc=uni-heidelberg,dc=de")

>>> db.session.add(l)

>>> db.session.commit()

>>> exit()

```

# Portal Architecture

# 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

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

## `/portal/`: Main Application

#### `/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.

See the [Frontend](./frontend.md) documentation for more details.

### `/portal/templates`

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

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

```

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.