# 📘 Gesthub
<img src="https://img.shields.io/github/last-commit/M1n-0/gesthub?style=flat&logo=git&logoColor=white&color=0080ff" alt="last-commit">

<p align="right">
  <a href="README.md"><img src="https://img.shields.io/badge/README-Fran%C3%A7ais-blue?style=flat&logo=readthedocs&logoColor=white" alt="README en français"></a>
</p>

> **Version v2 (August 2026).** The code has been reorganized into a
> layered architecture (`routes/`, `services/`, `models/`), with the
> Announcements, Files, and Planning modules, an `audit_log` table, and a
> suite of 34 automated tests (see `web/tests/`). This version serves as
> the technical support for the RNCP 36463 (CDAN) certification file: see
> `docs/` for the complete technical dossier
> (`docs/Dossier_technique_GestHub_v2.docx`) and the actual evidence
> (`docs/evidence/`: pytest/flake8/radon output, screenshots, architecture
> diagrams).
>
> Quick start:
> ```bash
> cp web/.env.example web/.env   # fill in the real values
> docker compose up -d --build
> ```
> Run the tests (requires an accessible test MariaDB database, see
> `web/tests/conftest.py`):
> ```bash
> cd web && pip install -r requirements.txt
> TEST_DB_NAME=gesthub_test DB_USER=... DB_PASSWORD=... DB_HOST=... pytest tests/ -v
> ```

<em>Built with the tools and technologies needed:</em>
<div style="display: flex; flex-wrap: wrap; gap: 5px;">
   <img src="https://img.shields.io/badge/Flask-000000.svg?style=flat&logo=Flask&logoColor=white" alt="Flask">
   <img src="https://img.shields.io/badge/JSON-000000.svg?style=flat&logo=JSON&logoColor=white" alt="JSON">
   <img src="https://img.shields.io/badge/Keycloak-4D4D4D.svg?style=flat&logo=Keycloak&logoColor=white" alt="Keycloak">
   <img src="https://img.shields.io/badge/GNU%20Bash-4EAA25.svg?style=flat&logo=GNU-Bash&logoColor=white" alt="GNU%20Bash">
   <img src="https://img.shields.io/badge/MariaDB-003545.svg?style=flat&logo=MariaDB&logoColor=white" alt="MariaDB">
   <br>
   <img src="https://img.shields.io/badge/Docker-2496ED.svg?style=flat&logo=Docker&logoColor=white" alt="Docker">
   <img src="https://img.shields.io/badge/Python-3776AB.svg?style=flat&logo=Python&logoColor=white" alt="Python">
   <img src="https://img.shields.io/badge/Mattermost-0058CC.svg?style=flat&logo=Mattermost&logoColor=white" alt="Mattermost">
</div>

## 🧱 Goal

Build a multi-service website (extranet/intranet) with:
- Centralized authentication via **Keycloak**
- **Caddy** reverse proxy
- **Flask** frontend/backend
- Chat & task management via **Mattermost**
- JSON-based announcement management with `/admin` permissions (to do)

---

## 🐳 Starting the project

### 1. **Docker structure**

The services are defined in `docker-compose.yml`:
- `caddy`: Reverse proxy + automatic HTTPS
- `flask`: Backend web application
- `mariadb`: Database
- `keycloak`: SSO + user management
- `mattermost`: Chat and task management (Trello-like)

Network used: `gesthub_gesthub`

---

## 🔐 Keycloak authentication

### ✅ Steps:

1. Create the **`Gesthub` realm**
2. Add the clients (Flask and Mattermost)
3. Enable `OpenID Connect`
4. Configure the **Redirect URIs**
   - Examples:
     - Flask → `https://dashboard.ninolbt.com/login/callback`
     - Mattermost → `https://mattermost.ninolbt.com/signup/openid/complete`

5. For `/admin` users, use the **`/admin` group** in Keycloak.

---

## 🍓 Deployment on Raspberry Pi (ARM64)

GestHub v2 is designed to run on a Raspberry Pi (4 or 5) with a **64-bit**
OS (Raspberry Pi OS 64-bit / Ubuntu Server 64-bit). Check first:

```bash
uname -m          # should print aarch64 (otherwise: reinstall the OS in 64-bit)
docker --version  # install via https://get.docker.com if missing
```

All the images in `docker-compose.yml` are official multi-arch images
(Caddy, MariaDB, Postgres, Keycloak) — Docker automatically selects the
arm64 variant on `pull`, nothing to change. The only exception is
`mattermost/mattermost-team-edition`, which is only published for
`linux/amd64` (no official ARM image to date — see
[mattermost/mattermost#21979](https://github.com/mattermost/mattermost/issues/21979)).
The compose file therefore uses an equivalent community build,
`ngrie/mattermost-team-edition-arm`, at the same version — see the comment
in `docker-compose.yml`. On an amd64 host (CI, dev machine), switch back to
the official `mattermost/mattermost-team-edition:9.11` image.

**RAM**: the full stack (Caddy + Flask + MariaDB + Keycloak + 2×Postgres +
Mattermost) runs simultaneously — plan for a Pi with **4 GB of RAM
minimum, 8 GB recommended**, and fast SSD/SD card storage (MariaDB/Postgres
volumes are sensitive to the slow I/O of a regular SD card).

---

## 🌐 Caddy reverse proxy

### 🛠️ `Caddyfile`:

```caddyfile
https://dashboard.ninolbt.com {
    reverse_proxy flask:5000
}

https://keycloak.ninolbt.com {
    reverse_proxy keycloak:8080
}

https://mattermost.ninolbt.com {
    reverse_proxy mattermost:8065
}
```

**Persistent volumes**:  
`caddy_data` and `caddy_config` mounted at `/data` and `/config`

---

## 🧩 Flask
- Dashboard backend
- Allows creating/editing/deleting announcements in JSON (being tested)
- Accessible only to users with the `/admin` role (via token) (being tested)
- Static asset loading fixed with Caddy

---

## 🗂️ Permissions management

- Auth via Keycloak for Flask, Mattermost, Wekan
- Group checks in Flask (`/admin`)
- Correct redirects with Caddy HTTPS URLs

---

## 📌 Bugs and fixes

- ⚠️ Incorrect Keycloak redirect → Fixed with the correct `redirect_uri`
- ⚠️ Flask static assets → fixed via absolute HTTPS URL
- ✅ Reverse proxy works with all services
- ✅ HTTPS operational via Caddy with Let's Encrypt certificates

---

## 🚀 Startup

```bash
docker compose up --build -d
```

If needed:
```bash
docker compose logs -f [service]
```

---

## 📤 Full export

To make the project exportable:
- Everything is containerized (Docker)
- Keycloak config exported (JSON available in the `export_keycloak` folder)
- `docker-compose.yml`, `Caddyfile`, files available in the repo