gesthub/README.en.md

📘 Gesthub

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:

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):

cd web && pip install -r requirements.txt
TEST_DB_NAME=gesthub_test DB_USER=... DB_PASSWORD=... DB_HOST=... pytest tests/ -v

Built with the tools and technologies needed:

🧱 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:

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). 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:

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

docker compose up --build -d

If needed:

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