jannis-patch-1 #41
246
README.md
246
README.md
@@ -1,38 +1,34 @@
|
|||||||
# 🗂️ 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) │
|
||||||
└─────────────────┘ └──────────┬───────────┘
|
└─────────────────┘ └──────────┬───────────┘
|
||||||
│
|
│
|
||||||
@@ -46,113 +42,108 @@ Jedes Repository, das auf dieser Gitea-Instanz mit dem Topic-Tag `dashboard` ver
|
|||||||
│ Frontend │
|
│ Frontend │
|
||||||
│ (SvelteKit) │
|
│ (SvelteKit) │
|
||||||
└──────────────────────┘
|
└──────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## 🖥️ 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
|
|
||||||
- `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)
|
|
||||||
|
|
||||||
**Beispiel – HTTP-Server ohne Framework:**
|
- `pgx` – PostgreSQL driver (direct SQL, no ORM)
|
||||||
```go
|
- `godotenv` – load `.env` file
|
||||||
mux := http.NewServeMux()
|
- `golang.org/x/oauth2` – OAuth2 flow for Gitea login
|
||||||
mux.HandleFunc("GET /api/projects", h.listProjects)
|
|
||||||
mux.HandleFunc("POST /api/webhook", h.handleWebhook)
|
|
||||||
mux.HandleFunc("GET /api/projects/{id}/issues", h.listIssues)
|
|
||||||
|
|
||||||
log.Fatal(http.ListenAndServe(":8080", mux))
|
**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)
|
||||||
|
|
||||||
## 🔐 Auth: **Gitea OAuth2**
|
**Example – HTTP server without a framework:**
|
||||||
|
|
||||||
Gitea kann selbst als OAuth2-Provider fungieren – Nutzer loggen sich mit ihrem Gitea-Account im Dashboard ein, genau wie "Login with GitHub".
|
```go
|
||||||
|
mux := http.NewServeMux()
|
||||||
|
mux.HandleFunc("GET /api/projects", h.listProjects)
|
||||||
|
mux.HandleFunc("POST /api/webhook", h.handleWebhook)
|
||||||
|
mux.HandleFunc("GET /api/projects/{id}/issues", h.listIssues)
|
||||||
|
|
||||||
### Setup in Gitea:
|
log.Fatal(http.ListenAndServe(":8080", mux))
|
||||||
|
```
|
||||||
|
|
||||||
1. In Gitea unter **Settings → Applications → OAuth2 Applications** eine neue App registrieren
|
## 🔐 Auth: Gitea OAuth2
|
||||||
2. `Client ID` und `Client Secret` in die `.env` eintragen
|
|
||||||
3. Redirect URI auf `https://dashboard.example.com/auth/callback` setzen
|
|
||||||
|
|
||||||
### Flow:
|
Gitea can act as its own OAuth2 provider – users log into the dashboard with their Gitea account, just like "Login with GitHub".
|
||||||
|
|
||||||
```
|
**Setup in Gitea:**
|
||||||
Nutzer klickt "Login mit Gitea"
|
1. In Gitea under **Settings → Applications → OAuth2 Applications**, register a new app
|
||||||
→ Weiterleitung zur Gitea-Instanz (Authorization Endpoint)
|
2. Enter Client ID and Client Secret in the `.env` file
|
||||||
→ Nutzer bestätigt Zugriff
|
3. Set the Redirect URI to `https://dashboard.example.com/auth/callback`
|
||||||
→ Gitea leitet mit Authorization Code zurück
|
|
||||||
→ Backend tauscht Code gegen Access Token
|
|
||||||
→ Nutzer ist eingeloggt, Gitea-Identität bekannt
|
|
||||||
```
|
|
||||||
|
|
||||||
**Vorteile:**
|
**Flow:**
|
||||||
- Kein eigenes Auth-System nötig – Gitea übernimmt Passwörter und Sessions
|
- User clicks "Login with Gitea"
|
||||||
- Nutzeridentität direkt bekannt → Repos und Issues können nutzerbasiert gefiltert werden
|
- → Redirect to Gitea instance (Authorization Endpoint)
|
||||||
- Schreibrechte (Issues erstellen/schließen) nur für den jeweiligen Repo-Owner
|
- → User confirms access
|
||||||
- Implementiert mit `golang.org/x/oauth2` – offizielles Go-Paket, keine Drittanbieter-Lib nötig
|
- → Gitea redirects back with Authorization Code
|
||||||
|
- → Backend exchanges code for Access Token
|
||||||
|
- → User is logged in, Gitea identity is known
|
||||||
|
|
||||||
---
|
**Advantages:**
|
||||||
|
|
||||||
## 🗄️ Datenbank: **PostgreSQL**
|
- 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
|
||||||
|
|
||||||
**Schema-Übersicht:**
|
## 🗄️ Database: PostgreSQL
|
||||||
|
|
||||||
```sql
|
**Schema overview:**
|
||||||
-- Gecachte Repo-Informationen
|
|
||||||
CREATE TABLE projects (
|
```sql
|
||||||
|
-- Cached repo information
|
||||||
|
CREATE TABLE projects (
|
||||||
id SERIAL PRIMARY KEY,
|
id SERIAL PRIMARY KEY,
|
||||||
gitea_id INTEGER UNIQUE NOT NULL,
|
gitea_id INTEGER UNIQUE NOT NULL,
|
||||||
name VARCHAR(255) NOT NULL,
|
name VARCHAR(255) NOT NULL,
|
||||||
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,
|
||||||
is_private BOOLEAN DEFAULT false,
|
is_private BOOLEAN DEFAULT false,
|
||||||
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,
|
||||||
project_id INTEGER REFERENCES projects(id),
|
project_id INTEGER REFERENCES projects(id),
|
||||||
@@ -161,58 +152,49 @@ CREATE TABLE issues (
|
|||||||
assignee VARCHAR(100),
|
assignee VARCHAR(100),
|
||||||
milestone TEXT,
|
milestone TEXT,
|
||||||
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),
|
||||||
payload JSONB,
|
payload JSONB,
|
||||||
received_at TIMESTAMPTZ DEFAULT NOW()
|
received_at TIMESTAMPTZ DEFAULT NOW()
|
||||||
);
|
);
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## 🚀 Roadmap
|
||||||
|
- v0.1 – Repo listing via tag `dashboard`, polling every 5 min
|
||||||
|
- v0.2 – Webhook listener for real-time updates
|
||||||
|
- v0.3 – Display issues & milestones in the dashboard
|
||||||
|
- v0.4 – Create/close issues directly from the dashboard (bi-directional)
|
||||||
|
- v0.5 – Gitea OAuth2 login
|
||||||
|
- v0.6 – Integration with freelancer dashboard (repos = projects)
|
||||||
|
- v1.0 – Multi-user, public project pages
|
||||||
|
|
||||||
## 🚀 Roadmap
|
## 🔧 Tech Stack
|
||||||
|
|
||||||
- [ ] **v0.1** – Repo-Listing via Tag `dashboard`, Polling alle 5 min
|
| Layer | Technology |
|
||||||
- [ ] **v0.2** – Webhook-Listener für Echtzeit-Updates
|
|----------|-------------------------------------|
|
||||||
- [ ] **v0.3** – Issues & Milestones im Dashboard anzeigen
|
| Frontend | SvelteKit + TailwindCSS |
|
||||||
- [ ] **v0.4** – Issues direkt aus dem Dashboard erstellen/schließen (bi-direktional)
|
| Backend | Go + net/http (standard lib) |
|
||||||
- [ ] **v0.5** – Gitea OAuth2 Login
|
| Database | PostgreSQL + pgx |
|
||||||
- [ ] **v0.6** – Verknüpfung mit Freelancer-Dashboard (Repos = Projekte)
|
| Auth | Gitea OAuth2 + golang.org/x/oauth2 |
|
||||||
- [ ] **v1.0** – Multi-User, öffentliche Projektsseiten
|
| API | Gitea REST API v1 |
|
||||||
|
| Deploy | Docker Compose |
|
||||||
|
|
||||||
---
|
## 📦 Getting Started
|
||||||
|
|
||||||
## 🔧 Tech Stack
|
```bash
|
||||||
|
# Clone the repo
|
||||||
|
git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard
|
||||||
|
|
||||||
| Schicht | Technologie |
|
# Set environment variables
|
||||||
|--------------|--------------------------------|
|
cp .env.example .env
|
||||||
| Frontend | SvelteKit + TailwindCSS |
|
# Fill in GITEA_URL, GITEA_TOKEN, GITEA_CLIENT_ID, GITEA_CLIENT_SECRET, DATABASE_URL, DASHBOARD_TAG
|
||||||
| Backend | Go + net/http (Standardlib) |
|
|
||||||
| Datenbank | PostgreSQL + pgx |
|
|
||||||
| Auth | Gitea OAuth2 + golang.org/x/oauth2 |
|
|
||||||
| API | Gitea REST API v1 |
|
|
||||||
| Deployment | Docker Compose |
|
|
||||||
|
|
||||||
---
|
# Start with Docker
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
## 📦 Getting Started
|
This project is part of the personal project ideas collection. Related overview repo: [projekt-ideen](https://gitea.starfour.de/Jannis/projekt-ideen)
|
||||||
|
|
||||||
```bash
|
|
||||||
# Repo klonen
|
|
||||||
git clone https://gitea.starfour.de/Jannis/gitea-projekt-dashboard
|
|
||||||
|
|
||||||
# Umgebungsvariablen setzen
|
|
||||||
cp .env.example .env
|
|
||||||
# GITEA_URL, GITEA_TOKEN, GITEA_CLIENT_ID, GITEA_CLIENT_SECRET, DATABASE_URL, DASHBOARD_TAG eintragen
|
|
||||||
|
|
||||||
# Mit Docker starten
|
|
||||||
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)*
|
|
||||||
Reference in New Issue
Block a user