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

revert: README zurückgesetzt auf Stand vor allgemeinem Projektmanager

Browse Source
This commit is contained in:
Jannis
2026-04-28 10:18:42 +00:00
parent 06a70a1e70
commit ca734e810d
1 changed files with 156 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

282
README.md
View File

@@ -1,219 +1,209 @@
# 🗂️ Projekt-Dashboard # 🗂️ Gitea Projekt-Dashboard
Ein selbst gehostetes Dashboard zur zentralen Verwaltung aller persönlichen Projekte – technische wie nicht-technische. Ein selbst gehostetes Dashboard, das automatisch alle Gitea-Repositories anzeigt, die mit einem bestimmten **Topic-Tag** versehen sind.
--- ---
## 💡 Was ist ein Projekt? ## 🏷️ Funktionsprinzip: Tag-basierte Projektanzeige
Ein Projekt ist **alles, woran aktiv gearbeitet wird oder wurde** – unabhängig davon, ob es einen Code-Repository hat oder nicht. Jedes Repository, das auf dieser Gitea-Instanz mit dem Topic-Tag `dashboard` versehen ist, wird automatisch im Dashboard angezeigt.
Beispiele: ### So funktioniert es:
- 🖥️ **Softwareprojekt** – eine selbst gehostete App, ein CLI-Tool, ein Backend-Service 1. Du setzt in einem Gitea-Repository unter **Settings → Topics** das Tag `dashboard`
- 🔧 **Hardware-Projekt** – Aufbau eines zweiten PCs, Einrichten eines Homelab-Servers 2. Der Backend-Service pollt regelmäßig (oder per Webhook) die Gitea API nach allen Repos mit diesem Tag
- 🏗️ **Infrastruktur** – Umstrukturierung des Heimnetzwerks, Migration zu Docker Compose 3. Die gefundenen Repos werden in der PostgreSQL-Datenbank gespeichert und gecacht
- 📋 **Organisatorisches** – Dokumentation aufräumen, Backupstrategie planen 4. Das Frontend zeigt alle getaggten Repos als Projektkarten mit Live-Daten an
- 🌱 **Persönliches** – Lernprojekte, Kurse, Ziele ohne technischen Bezug
Ein Projekt **kann** mit einer Gitea-Repository verknüpft sein, **muss es aber nicht**. > **Beispiel:** Repo `mein-projekt` bekommt das Topic `dashboard` → erscheint sofort im Dashboard mit Issues, letztem Commit, Status und Beschreibung.
---
## 🏷️ Repo-Verknüpfung (optional)
Wenn ein Projekt eine zugehörige Gitea-Repository hat, kann diese durch das Topic-Tag `projekt` markiert werden. Das Dashboard erkennt diese Repos automatisch und zeigt zugehörige Metadaten an (letzter Commit, offene Issues, Sprache etc.).
Repos **ohne** das Tag `projekt` erscheinen nicht im Dashboard – sie sind keine verwalteten Projekte.
Projekte **ohne** Repository existieren nur in der Datenbank des Dashboards und werden manuell angelegt.
--- ---
## 🧱 Architektur ## 🧱 Architektur
``` ```
┌─────────────────────┐ Gitea REST API v1 ┌──────────────────────┐ ┌─────────────────┐ Gitea REST API v1 ┌──────────────────────┐
│ Gitea Server │ ◄─────────────────────────────► │ Backend Service │ │ Gitea Server │ ◄────────────────────────► │ Backend Service │
│ (Repos + Topics) │ (nur wenn Repo verknüpft) │ (Go, net/http) │ │ (Repos + Topics)│ │ (Go, net/http) │
└─────────────────────┘ └──────────┬───────────┘ └─────────────────┘ └──────────┬───────────┘
│ │
┌──────────▼───────────┐ ┌──────────▼───────────┐
│ PostgreSQL DB │ │ PostgreSQL DB │
│ (Projekte, Tasks, │ │ (Repos, Issues, │
│ Milestones, Notizen) │ │ Milestones, Cache) │
└──────────┬───────────┘ └──────────┬───────────┘
│ │
┌──────────▼───────────┐ ┌──────────▼───────────┐
│ Frontend │ │ Frontend │
│ (SvelteKit) │ │ (SvelteKit) │
└──────────────────────┘ └──────────────────────┘
``` ```
--- ---
## 🖥️ Frontend: SvelteKit ## 🖥️ Frontend: **SvelteKit**
Warum SvelteKit? **Warum SvelteKit?**
- Leichtgewichtig und schnell – ideal für ein internes Dashboard
- Server-Side Rendering (SSR) out of the box – kein Flackern beim Laden
- Einfache Reaktivität ohne Overhead
- Perfekt für datengetriebene Dashboards mit Echtzeit-Updates via SSE oder WebSocket
- Leichtgewichtig und schnell – ideal für ein internes Dashboard **Features im Frontend:**
- Server-Side Rendering (SSR) out of the box – kein Flackern beim Laden - Projektkarten mit Repo-Name, Beschreibung, letztem Commit, offenen Issues
- Einfache Reaktivität ohne Overhead - Filterfunktion nach Topics, Sprache, Aktivität
- Perfekt für datengetriebene Übersichten mit Echtzeit-Updates - Detailansicht: Issues & Milestones direkt im Dashboard bearbeiten (bi-direktional)
- Live-Updates via Webhook-Events (Server-Sent Events)
- Dark Mode, responsive Design
Features im Frontend: ---
- Projektkarten mit Name, Beschreibung, Status und offenen Tasks ## ⚙️ Backend: **Go (net/http + pgx)**
- Unterscheidung zwischen repo-gebundenen und freien Projekten
- Filterfunktion nach Kategorie, Status, Aktivität
- Detailansicht: Tasks, Milestones, Notizen pro Projekt
- Live-Updates via Server-Sent Events (bei repo-gebundenen Projekten)
- Dark Mode, responsive Design
--- 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.
## ⚙️ Backend: Go (net/http + pgx) **Warum kein 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
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. **Externe Dependencies (minimal):**
- `pgx` – PostgreSQL-Treiber (direktes SQL, kein ORM)
- `godotenv` – `.env`-Datei laden
- `golang.org/x/oauth2` – OAuth2-Flow für Gitea-Login
**Warum kein Framework?** **Backend-Aufgaben:**
- `GET /api/projects` – alle getaggten Repos aus der DB zurückgeben
- `POST /api/webhook` – Gitea Webhook-Listener für Push, Issue, Tag-Events
- `GET /api/projects/{id}/issues` – Issues eines Repos live aus Gitea holen
- Hintergrund-Goroutine: alle 5 Minuten Gitea API nach Repos mit Tag `dashboard` abfragen
- Repo-Daten in PostgreSQL cachen (inkl. Topics, letzter Aktivität, Issue-Count)
- `net/http` aus der Standardbibliothek reicht für die benötigten Endpoints vollständig aus **Beispiel – HTTP-Server ohne Framework:**
- Kein Framework-Overhead, keine Breaking Changes durch externe Dependencies ```go
- Go-typischer Ansatz: explizit, simpel, lesbar mux := http.NewServeMux()
- Kompiliert zu einer einzigen statischen Binary – minimaler Docker-Footprint mux.HandleFunc("GET /api/projects", h.listProjects)
mux.HandleFunc("POST /api/webhook", h.handleWebhook)
mux.HandleFunc("GET /api/projects/{id}/issues", h.listIssues)
**Externe Dependencies (minimal):** log.Fatal(http.ListenAndServe(":8080", mux))
```
- `pgx` – PostgreSQL-Treiber (direktes SQL, kein ORM) ---
- `godotenv` – `.env`-Datei laden
- `golang.org/x/oauth2` – OAuth2-Flow für Gitea-Login (optional)
**Backend-Aufgaben:** ## 🔐 Auth: **Gitea OAuth2**
- `GET /api/projects` – alle Projekte aus der DB zurückgeben Gitea kann selbst als OAuth2-Provider fungieren – Nutzer loggen sich mit ihrem Gitea-Account im Dashboard ein, genau wie "Login with GitHub".
- `POST /api/projects` – neues Projekt anlegen (mit oder ohne Repo-Verknüpfung)
- `GET /api/projects/{id}/tasks` – Tasks eines Projekts abrufen
- `POST /api/webhook` – Gitea Webhook-Listener für repo-gebundene Projekte
- Hintergrund-Goroutine: Gitea API nach Repos mit Tag `projekt` abfragen und DB synchronisieren
--- ### Setup in Gitea:
## 🔐 Auth: Gitea OAuth2 1. In Gitea unter **Settings → Applications → OAuth2 Applications** eine neue App registrieren
2. `Client ID` und `Client Secret` in die `.env` eintragen
3. Redirect URI auf `https://dashboard.example.com/auth/callback` setzen
Gitea fungiert als OAuth2-Provider – Nutzer loggen sich mit ihrem Gitea-Account im Dashboard ein. ### Flow:
**Flow:** ```
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
```
Nutzer klickt "Login mit Gitea" → Weiterleitung zur Gitea-Instanz → Nutzer bestätigt Zugriff → Gitea leitet mit Authorization Code zurück → Backend tauscht Code gegen Access Token → Nutzer ist eingeloggt **Vorteile:**
- 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
**Vorteile:** ---
- Kein eigenes Auth-System nötig ## 🗄️ Datenbank: **PostgreSQL**
- Nutzeridentität direkt bekannt
- Implementiert mit `golang.org/x/oauth2`
--- **Schema-Übersicht:**
## 🗄️ Datenbank: PostgreSQL ```sql
-- Gecachte Repo-Informationen
**Schema-Übersicht:** CREATE TABLE projects (
```sql
-- Alle Projekte (mit oder ohne Repo-Verknüpfung)
CREATE TABLE projects (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
gitea_id INTEGER UNIQUE NOT NULL,
name VARCHAR(255) NOT NULL, name VARCHAR(255) NOT NULL,
full_name VARCHAR(255) NOT NULL,
description TEXT, description TEXT,
status VARCHAR(50) DEFAULT 'active', -- active / paused / done html_url TEXT,
category VARCHAR(100), -- z.B. "software", "hardware", "infra", "personal" topics TEXT[], -- z.B. ["dashboard", "freelancer"]
gitea_repo TEXT, -- optional: voller Repo-Name (z.B. "Jannis/mein-projekt") language VARCHAR(100),
gitea_id INTEGER, -- optional: Gitea-interne Repo-ID open_issues INTEGER DEFAULT 0,
html_url TEXT, -- optional: Link zur Repo last_push TIMESTAMPTZ,
language VARCHAR(100), -- optional: Hauptsprache der Repo is_private BOOLEAN DEFAULT false,
open_tasks INTEGER DEFAULT 0, synced_at TIMESTAMPTZ DEFAULT NOW()
last_activity TIMESTAMPTZ, );
created_at TIMESTAMPTZ DEFAULT NOW(),
synced_at TIMESTAMPTZ -- NULL wenn kein Gitea-Sync
);
-- Tasks / Aufgaben pro Projekt -- Gemanagte Issues / Aufgaben
CREATE TABLE tasks ( CREATE TABLE issues (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
gitea_id INTEGER NOT NULL,
project_id INTEGER REFERENCES projects(id), project_id INTEGER REFERENCES projects(id),
gitea_issue_id INTEGER, -- optional: verknüpftes Gitea-Issue
title TEXT NOT NULL, title TEXT NOT NULL,
body TEXT, state VARCHAR(20), -- open / closed
state VARCHAR(20) DEFAULT 'open', -- open / closed
priority VARCHAR(20), -- low / medium / high
milestone TEXT,
assignee VARCHAR(100), assignee VARCHAR(100),
updated_at TIMESTAMPTZ DEFAULT NOW() milestone TEXT,
); updated_at TIMESTAMPTZ
);
-- Milestones pro Projekt -- Webhook-Event-Log
CREATE TABLE milestones ( CREATE TABLE webhook_events (
id SERIAL PRIMARY KEY,
project_id INTEGER REFERENCES projects(id),
title TEXT NOT NULL,
description TEXT,
due_date TIMESTAMPTZ,
closed BOOLEAN DEFAULT false
);
-- Webhook-Event-Log (nur für repo-gebundene Projekte)
CREATE TABLE webhook_events (
id SERIAL PRIMARY KEY, id SERIAL PRIMARY KEY,
event_type VARCHAR(50), event_type VARCHAR(50),
project_id INTEGER REFERENCES projects(id),
payload JSONB, payload JSONB,
received_at TIMESTAMPTZ DEFAULT NOW() received_at TIMESTAMPTZ DEFAULT NOW()
); );
``` ```
--- ---
## 🚀 Roadmap ## 🚀 Roadmap
- **v0.1** – Projekt-Listing: manuelle Projekte anlegen, Repos mit Tag `projekt` automatisch einlesen - [ ] **v0.1** – Repo-Listing via Tag `dashboard`, Polling alle 5 min
- **v0.2** – Webhook-Listener für Echtzeit-Sync bei repo-gebundenen Projekten - [ ] **v0.2** – Webhook-Listener für Echtzeit-Updates
- **v0.3** – Tasks & Milestones im Dashboard anzeigen und verwalten - [ ] **v0.3** – Issues & Milestones im Dashboard anzeigen
- **v0.4** – Tasks direkt aus dem Dashboard erstellen/schließen (bi-direktional mit Gitea) - [ ] **v0.4** – Issues direkt aus dem Dashboard erstellen/schließen (bi-direktional)
- **v0.5** – Gitea OAuth2 Login - [ ] **v0.5** – Gitea OAuth2 Login
- **v0.6** – Kategorien, Filter, Status-Verwaltung für alle Projekttypen - [ ] **v0.6** – Verknüpfung mit Freelancer-Dashboard (Repos = Projekte)
- **v1.0** – Multi-User, öffentliche Projektseiten - [ ] **v1.0** – Multi-User, öffentliche Projektsseiten
--- ---
## 🔧 Tech Stack ## 🔧 Tech Stack
| Schicht | Technologie | | Schicht | Technologie |
|-------------|-------------------------------------| |--------------|--------------------------------|
| Frontend | SvelteKit + TailwindCSS | | Frontend | SvelteKit + TailwindCSS |
| Backend | Go + net/http (Standardlib) | | Backend | Go + net/http (Standardlib) |
| Datenbank | PostgreSQL + pgx | | Datenbank | PostgreSQL + pgx |
| Auth | Gitea OAuth2 + golang.org/x/oauth2 | | Auth | Gitea OAuth2 + golang.org/x/oauth2 |
| API | Gitea REST API v1 (optional) | | API | Gitea REST API v1 |
| Deployment | Docker Compose | | Deployment | Docker Compose |
--- ---
## 📦 Getting Started ## 📦 Getting Started
```bash ```bash
# Repo klonen # Repo klonen
git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard
# Umgebungsvariablen setzen # Umgebungsvariablen setzen
cp .env.example .env cp .env.example .env
# GITEA_URL, GITEA_TOKEN, DATABASE_URL, PROJEKT_TAG eintragen # GITEA_URL, GITEA_TOKEN, GITEA_CLIENT_ID, GITEA_CLIENT_SECRET, DATABASE_URL, DASHBOARD_TAG eintragen
# Mit Docker starten # Mit Docker starten
docker compose up -d docker compose up -d
``` ```
--- ---
Dieses Projekt ist Teil der persönlichen Projekt-Ideen-Sammlung.
Zugehöriges Übersichts-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)*