Jannis/gitea-projekt-dashboard
1
0
Fork 0
Code Issues 35 Pull Requests Actions Projects Releases Wiki Activity

Compare commits

base: Jannis:bf86667aec34435404817757a2598f4cc66a008f
Branches Tags
Jannis:master Jannis:dev
...
compare: Jannis:bff0986e887cbd7b933fdfa079148ec540a61772
Branches Tags
Jannis:master Jannis:dev

3 Commits
bf86667aec ... bff0986e88

Author SHA1 Message Date
Jannis
bff0986e88 Merge pull request 'jannis-patch-1' (#40) from jannis-patch-1 into master 
Reviewed-on: #40
 2026-05-13 08:38:10 +00:00
Jannis
8b5cee8a6f Update README.md 2026-05-13 08:36:54 +00:00
Jannis
cb2700066a Update README.md 2026-05-13 08:11:47 +00:00
1 changed files with 130 additions and 147 deletions
Expand all files Collapse all files

201
README.md
View File

@@ -1,40 +1,37 @@
# 🗂️ Gitea Projekt-Dashboard # 🗂️ Gitea Project Dashboard
> [!WARNING] > [!WARNING]
> **⏸️ Projekt pausiert** > **⏸️ Project paused**
> >
> Dieses Projekt ist aktuell pausiert. Ich entwickle eine eigene Lösung weiter, die Beego ersetzen soll. > This project is currently paused. I am continuing to develop my own solution to replace Beego. Once my own web framework is far enough along, this project will be rebuilt with it.
> Sobald mein eigenes Web-Framework weit genug ist, wird dieses Projekt damit neu aufgesetzt.
> >
> 👉 **Eigene Lösung in Entwicklung:** [go-webframework](https://gitea.starfour.de/Jannis/go-webframework) > 👉 **Own solution in development:** [go-webframework](https://gitea.starfour.de/Jannis/go-webframework)
A self-hosted dashboard for centrally managing all personal projects – technical and non-technical alike. Projects can be linked to a Gitea repository, but don't have to be.
Ein selbst gehostetes Dashboard zur zentralen Verwaltung aller persönlichen Projekte – technische wie nicht-technische. Projekte können mit einer Gitea-Repository verknüpft sein, müssen es aber nicht.
--- ---
## 🏷️ Funktionsprinzip: Tag-basierte Projektanzeige ## 🏷️ How It Works: Tag-Based Project Display
Jedes Repository, das auf dieser Gitea-Instanz mit dem Topic-Tag `dashboard` versehen ist, wird automatisch im Dashboard angezeigt. Every repository on this Gitea instance that has the topic tag `dashboard` is automatically shown in the dashboard.
### So funktioniert es: ### How it works:
1. In a Gitea repository, go to **Settings → Topics** and add the tag `dashboard`
2. The backend service polls the Gitea API regularly (or via webhook) for all repos with this tag
3. The found repos are stored and cached in the PostgreSQL database
4. The frontend displays all tagged repos as project cards with live data
1. Du setzt in einem Gitea-Repository unter **Settings → Topics** das Tag `dashboard` > **Example:** Repo `my-project` gets the topic `dashboard` → immediately appears in the dashboard with issues, last commit, status, and description.
2. Der Backend-Service pollt regelmäßig (oder per Webhook) die Gitea API nach allen Repos mit diesem Tag
3. Die gefundenen Repos werden in der PostgreSQL-Datenbank gespeichert und gecacht
4. Das Frontend zeigt alle getaggten Repos als Projektkarten mit Live-Daten an
> **Beispiel:** Repo `mein-projekt` bekommt das Topic `dashboard` → erscheint sofort im Dashboard mit Issues, letztem Commit, Status und Beschreibung.
--- ---
## 🧱 Architektur ## 🧱 Architecture
``` ```
┌─────────────────┐ Gitea REST API v1 ┌──────────────────────┐ ┌─────────────────┐ Gitea REST API v1 ┌─────────────────────┐
│ Gitea Server │ ◄────────────────────────► │ Backend Service │ │ Gitea Server │ ◄────────────────────► │ Backend Service │
│ (Repos + Topics)│ │ (Go, net/http) │ │ (Repos + Topics)│ │ (Go, net/http) │
└─────────────────┘ └──────────┬───────────┘ └─────────────────┘ └──────────┬──────────┘
│ │
┌──────────▼───────────┐ ┌──────────▼───────────┐
│ PostgreSQL DB │ │ PostgreSQL DB │
@@ -48,48 +45,50 @@ Jedes Repository, das auf dieser Gitea-Instanz mit dem Topic-Tag `dashboard` ver
└──────────────────────┘ └──────────────────────┘
``` ```
--- ## 🖥️ Frontend: SvelteKit
## 🖥️ Frontend: **SvelteKit** **Why SvelteKit?**
**Warum SvelteKit?** - Lightweight and fast – ideal for an internal dashboard
- Leichtgewichtig und schnell – ideal für ein internes Dashboard - Server-Side Rendering (SSR) out of the box – no flickering on load
- Server-Side Rendering (SSR) out of the box – kein Flackern beim Laden - Simple reactivity without overhead
- Einfache Reaktivität ohne Overhead - Perfect for data-driven dashboards with real-time updates via SSE or WebSocket
- Perfekt für datengetriebene Dashboards mit Echtzeit-Updates via SSE oder WebSocket
**Features im Frontend:** **Frontend features:**
- Projektkarten mit Repo-Name, Beschreibung, letztem Commit, offenen Issues
- Filterfunktion nach Topics, Sprache, Aktivität
- Detailansicht: Issues & Milestones direkt im Dashboard bearbeiten (bi-direktional)
- Live-Updates via Webhook-Events (Server-Sent Events)
- Dark Mode, responsive Design
--- - Project cards with repo name, description, last commit, open issues
- Filter function by topics, language, activity
- Detail view: edit issues & milestones directly in the dashboard (bi-directional)
- Live updates via webhook events (Server-Sent Events)
- Dark mode, responsive design
## ⚙️ Backend: **Go (net/http + pgx)** ## ⚙️ Backend: Go (net/http + pgx)
Go eignet sich hervorragend als Backend-Sprache – die Standardbibliothek ist so vollständig, dass kein Web-Framework nötig ist. `net/http` liefert alles was gebraucht wird: Routing, Handler, Middleware. Das Ergebnis ist eine dependency-arme, gut lesbare Codebasis. Go is an excellent backend language – the standard library is so complete that no web framework is needed. `net/http` provides everything required: routing, handlers, middleware. The result is a dependency-light, readable codebase.
**Warum kein Framework?** **Why no framework?**
- `net/http` aus der Standardbibliothek reicht für ~6 Endpoints vollständig aus
- Kein Framework-Overhead, keine Breaking Changes durch externe Dependencies
- Go-typischer Ansatz: explizit, simpel, lesbar
- Kompiliert zu einer einzigen statischen Binary – minimaler Docker-Footprint
**Externe Dependencies (minimal):** - `net/http` from the standard library is fully sufficient for ~6 endpoints
- `pgx` – PostgreSQL-Treiber (direktes SQL, kein ORM) - No framework overhead, no breaking changes from external dependencies
- `godotenv` – `.env`-Datei laden - The Go-typical approach: explicit, simple, readable
- `golang.org/x/oauth2` – OAuth2-Flow für Gitea-Login - Compiles to a single static binary – minimal Docker footprint
**Backend-Aufgaben:** **External dependencies (minimal):**
- `GET /api/projects` – alle getaggten Repos aus der DB zurückgeben
- `POST /api/webhook` – Gitea Webhook-Listener für Push, Issue, Tag-Events - `pgx` – PostgreSQL driver (direct SQL, no ORM)
- `GET /api/projects/{id}/issues` – Issues eines Repos live aus Gitea holen - `godotenv` – load `.env` file
- Hintergrund-Goroutine: alle 5 Minuten Gitea API nach Repos mit Tag `dashboard` abfragen - `golang.org/x/oauth2` – OAuth2 flow for Gitea login
- Repo-Daten in PostgreSQL cachen (inkl. Topics, letzter Aktivität, Issue-Count)
**Backend tasks:**
- `GET /api/projects` – return all tagged repos from the DB
- `POST /api/webhook` – Gitea webhook listener for push, issue, tag events
- `GET /api/projects/{id}/issues` – fetch issues for a repo live from Gitea
- Background goroutine: query Gitea API every 5 minutes for repos with tag `dashboard`
- Cache repo data in PostgreSQL (incl. topics, last activity, issue count)
**Example – HTTP server without a framework:**
**Beispiel – HTTP-Server ohne Framework:**
```go ```go
mux := http.NewServeMux() mux := http.NewServeMux()
mux.HandleFunc("GET /api/projects", h.listProjects) mux.HandleFunc("GET /api/projects", h.listProjects)
@@ -99,43 +98,36 @@ mux.HandleFunc("GET /api/projects/{id}/issues", h.listIssues)
log.Fatal(http.ListenAndServe(":8080", mux)) log.Fatal(http.ListenAndServe(":8080", mux))
``` ```
--- ## 🔐 Auth: Gitea OAuth2
## 🔐 Auth: **Gitea OAuth2** Gitea can act as its own OAuth2 provider – users log into the dashboard with their Gitea account, just like "Login with GitHub".
Gitea kann selbst als OAuth2-Provider fungieren – Nutzer loggen sich mit ihrem Gitea-Account im Dashboard ein, genau wie "Login with GitHub". **Setup in Gitea:**
1. In Gitea under **Settings → Applications → OAuth2 Applications**, register a new app
2. Enter Client ID and Client Secret in the `.env` file
3. Set the Redirect URI to `https://dashboard.example.com/auth/callback`
### Setup in Gitea: **Flow:**
- User clicks "Login with Gitea"
- → Redirect to Gitea instance (Authorization Endpoint)
- → User confirms access
- → Gitea redirects back with Authorization Code
- → Backend exchanges code for Access Token
- → User is logged in, Gitea identity is known
1. In Gitea unter **Settings → Applications → OAuth2 Applications** eine neue App registrieren **Advantages:**
2. `Client ID` und `Client Secret` in die `.env` eintragen
3. Redirect URI auf `https://dashboard.example.com/auth/callback` setzen
### Flow: - No custom auth system needed – Gitea handles passwords and sessions
- User identity directly available → repos and issues can be filtered per user
- Write permissions (create/close issues) only for the respective repo owner
- Implemented with `golang.org/x/oauth2` – official Go package, no third-party lib needed
``` ## 🗄️ Database: PostgreSQL
Nutzer klickt "Login mit Gitea"
→ Weiterleitung zur Gitea-Instanz (Authorization Endpoint)
→ Nutzer bestätigt Zugriff
→ Gitea leitet mit Authorization Code zurück
→ Backend tauscht Code gegen Access Token
→ Nutzer ist eingeloggt, Gitea-Identität bekannt
```
**Vorteile:** **Schema overview:**
- Kein eigenes Auth-System nötig – Gitea übernimmt Passwörter und Sessions
- Nutzeridentität direkt bekannt → Repos und Issues können nutzerbasiert gefiltert werden
- Schreibrechte (Issues erstellen/schließen) nur für den jeweiligen Repo-Owner
- Implementiert mit `golang.org/x/oauth2` – offizielles Go-Paket, keine Drittanbieter-Lib nötig
---
## 🗄️ Datenbank: **PostgreSQL**
**Schema-Übersicht:**
```sql ```sql
-- Gecachte Repo-Informationen -- Cached repo information
CREATE TABLE projects ( CREATE TABLE projects (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
gitea_id INTEGER UNIQUE NOT NULL, gitea_id INTEGER UNIQUE NOT NULL,
@@ -143,7 +135,7 @@ CREATE TABLE projects (
full_name VARCHAR(255) NOT NULL, full_name VARCHAR(255) NOT NULL,
description TEXT, description TEXT,
html_url TEXT, html_url TEXT,
topics TEXT[], -- z.B. ["dashboard", "freelancer"] topics TEXT[], -- e.g. ["dashboard", "freelancer"]
language VARCHAR(100), language VARCHAR(100),
open_issues INTEGER DEFAULT 0, open_issues INTEGER DEFAULT 0,
last_push TIMESTAMPTZ, last_push TIMESTAMPTZ,
@@ -151,7 +143,7 @@ CREATE TABLE projects (
synced_at TIMESTAMPTZ DEFAULT NOW() synced_at TIMESTAMPTZ DEFAULT NOW()
); );
-- Gemanagte Issues / Aufgaben -- Managed issues / tasks
CREATE TABLE issues ( CREATE TABLE issues (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
gitea_id INTEGER NOT NULL, gitea_id INTEGER NOT NULL,
@@ -163,7 +155,7 @@ CREATE TABLE issues (
updated_at TIMESTAMPTZ updated_at TIMESTAMPTZ
); );
-- Webhook-Event-Log -- Webhook event log
CREATE TABLE webhook_events ( CREATE TABLE webhook_events (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
event_type VARCHAR(50), event_type VARCHAR(50),
@@ -172,47 +164,38 @@ CREATE TABLE webhook_events (
); );
``` ```
---
## 🚀 Roadmap ## 🚀 Roadmap
- v0.1 – Repo listing via tag `dashboard`, polling every 5 min
- [ ] **v0.1** – Repo-Listing via Tag `dashboard`, Polling alle 5 min - v0.2 – Webhook listener for real-time updates
- [ ] **v0.2** – Webhook-Listener für Echtzeit-Updates - v0.3 – Display issues & milestones in the dashboard
- [ ] **v0.3** – Issues & Milestones im Dashboard anzeigen - v0.4 – Create/close issues directly from the dashboard (bi-directional)
- [ ] **v0.4** – Issues direkt aus dem Dashboard erstellen/schließen (bi-direktional) - v0.5 – Gitea OAuth2 login
- [ ] **v0.5** – Gitea OAuth2 Login - v0.6 – Integration with freelancer dashboard (repos = projects)
- [ ] **v0.6** – Verknüpfung mit Freelancer-Dashboard (Repos = Projekte) - v1.0 – Multi-user, public project pages
- [ ] **v1.0** – Multi-User, öffentliche Projektsseiten
---
## 🔧 Tech Stack ## 🔧 Tech Stack
| Schicht | Technologie | | Layer | Technology |
|--------------|--------------------------------| |----------|-------------------------------------|
| Frontend | SvelteKit + TailwindCSS | | Frontend | SvelteKit + TailwindCSS |
| Backend | Go + net/http (Standardlib) | | Backend | Go + net/http (standard lib) |
| Datenbank | PostgreSQL + pgx | | Database | PostgreSQL + pgx |
| Auth | Gitea OAuth2 + golang.org/x/oauth2 | | Auth | Gitea OAuth2 + golang.org/x/oauth2 |
| API | Gitea REST API v1 | | API | Gitea REST API v1 |
| Deployment | Docker Compose | | Deploy | Docker Compose |
---
## 📦 Getting Started ## 📦 Getting Started
```bash ```bash
# Repo klonen # Clone the repo
git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard
# Umgebungsvariablen setzen # Set environment variables
cp .env.example .env cp .env.example .env
# GITEA_URL, GITEA_TOKEN, GITEA_CLIENT_ID, GITEA_CLIENT_SECRET, DATABASE_URL, DASHBOARD_TAG eintragen # Fill in GITEA_URL, GITEA_TOKEN, GITEA_CLIENT_ID, GITEA_CLIENT_SECRET, DATABASE_URL, DASHBOARD_TAG
# Mit Docker starten # Start with Docker
docker compose up -d docker compose up -d
``` ```
--- This project is part of the personal project ideas collection. Related overview repo: [projekt-ideen](https://gitea.starfour.de/Jannis/projekt-ideen)
*Dieses Projekt ist Teil der persönlichen Projekt-Ideen-Sammlung. Zugehöriges Übersichts-Repo: [projekt-ideen](https://gitea.starfour.de/Jannis/projekt-ideen)*