180 lines
6.0 KiB
Markdown
180 lines
6.0 KiB
Markdown
# 📘 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
|