Portfolio VitePress

Quellcode für eine statische Portfolio-Website auf Basis von VitePress. Die Seite ist auf Deutsch gepflegt und stellt Projektbeispiele zu Edge-IIoT, lokaler KI, Automatisierung und datengetriebenen Workflows vor.

Die Website wird lokal und in Forgejo Actions aus den Markdown-Inhalten unter docs/ gebaut. Der produktive Build entsteht unter docs/.vitepress/dist/ und wird per FTPS auf den Webserver übertragen.

Voraussetzungen

• Node.js 20 oder neuer für lokale Entwicklung
• npm
• Git

Der Forgejo Runner nutzt im Workflow Node.js 22.

Installation

npm install

Im CI/CD-Workflow wird stattdessen npm ci verwendet, damit exakt die im package-lock.json fixierten Abhängigkeiten installiert werden.

Entwicklung

Lokalen Entwicklungsserver starten:

npm run dev

VitePress startet damit im Dev-Modus für den Ordner docs/. Im Dev Container ist die Seite danach typischerweise unter http://localhost:5173/ erreichbar.

Build und Check

Produktiven Build lokal prüfen:

npm run check

Der Check führt aktuell aus:

npm run clean && npm run build

Dabei werden alte VitePress-Caches und Build-Ausgaben entfernt und danach ein frischer Build erzeugt.

Der fertige Build liegt danach hier:

docs/.vitepress/dist/

Dieser Ordner wird nicht versioniert, sondern bei Bedarf neu erzeugt.

Nützliche Scripts

npm run dev

Startet die lokale VitePress-Entwicklung.

npm run build

Erstellt den produktiven VitePress-Build.

npm run preview

Startet eine lokale Vorschau des produktiven Builds.

npm run clean

Entfernt VitePress-Temporärdateien, Cache und Build-Ausgabe.

npm run check

Führt Clean und Build zusammen aus. Dieser Befehl ist der zentrale Validierungsschritt im Forgejo Workflow.

npm run format

Formatiert Markdown-Dateien unter docs/ mit Prettier.

Projektstruktur

docs/

Markdown-Inhalte, VitePress-Konfiguration und Theme-Anpassungen.

docs/projects/

Projektseiten. Die einzelnen Projektseiten importieren die Galerie-Komponente und übergeben die jeweiligen Bilder als Array mit src, alt und optionaler caption.

docs/.vitepress/config.js

Zentrale VitePress-Konfiguration, unter anderem Navigation, Sidebar, Head-Tags und Footer.

docs/.vitepress/theme/

Theme-Erweiterungen, globale Styles und Vue-Komponenten.

docs/.vitepress/theme/components/ProjectGallery.vue

Schlanker Container für Projektgalerien. Die Komponente rendert den Embla- Viewport, die Bild-Slides, die Indikatoren und die Bildunterschrift.

docs/.vitepress/theme/components/project-gallery/

Ausgelagerte Galerie-Bausteine:

• ProjectGalleryControls.vue: Steuerleiste für Zurück, Pause/Start, vergrößerte Ansicht und Weiter.
• ProjectGalleryPreview.vue: nicht-vollbildiges Overlay für die größere Bildansicht.
• useProjectGalleryCarousel.js: Embla-Initialisierung, Autoplay, Timer-Reset, Preview-Pause und Fortschrittswert für den aktiven Indikator.

docs/public/

Statische Assets. Alles in diesem Ordner wird von VitePress in den Build kopiert, zum Beispiel Diagramme, Beispielbilder, Fonts und Favicons.

docs/public/pictures/

Bilder für die Projektgalerien. Jedes Projekt hat einen eigenen Unterordner, zum Beispiel edge-platform, document-processing, cost-accounting oder industrial-knowledge-systems. Die Dateien sind im Build direkt unter /pictures/<projekt>/<datei> erreichbar. SVG, JPG, JPEG, PNG und WebP können als normale Bildquellen in den Galerien verwendet werden.

Projektgalerien

Die Projektgalerien basieren auf embla-carousel-vue und embla-carousel-autoplay. Sie rotieren automatisch, können manuell pausiert und über Zurück/Weiter sowie die Indikatoren bedient werden.

Der aktive Indikator ist keine einfache Punktmarkierung, sondern eine kleine abgerundete Fortschrittsleiste. Sie füllt sich mit der Markenfarbe, solange der Autoplay-Timer bis zum nächsten Bild läuft. Bei manueller Navigation wird der Timer neu gestartet.

Die vergrößerte Bildansicht ist bewusst kein Browser-Vollbild. Beim Öffnen wird die Rotation pausiert; nach dem Schließen setzt sie mit dem gemerkten Fortschritt fort, sofern die Galerie nicht vorher manuell pausiert wurde.

.forgejo/workflows/deploy.yml

Forgejo Actions Workflow für Build und Deployment.

misc/platzhalter/
misc/vorlagen/
misc/favicon/

Zusätzliche lokale Materialien und Vorlagen. Diese Ordner sind nicht Teil des VitePress-Builds, solange sie nicht unter docs/public/ referenziert oder kopiert werden.

Deployment

Das Deployment läuft über Forgejo Actions.

Der Workflow wird ausgelöst durch:

on:
  workflow_dispatch:
  push:
    branches:
      - main

Damit gibt es zwei Wege:

• automatisch bei jedem Push beziehungsweise Merge nach main
• manuell über den Forgejo Actions Tab durch workflow_dispatch

Der Workflow führt aus:

1. Repository auschecken
2. Node.js 22 bereitstellen
3. Abhängigkeiten mit npm ci installieren
4. Website mit npm run check validieren und bauen
5. lftp installieren
6. Inhalt von docs/.vitepress/dist/ per FTPS auf den Webserver spiegeln

Forgejo Runner

Der Job verwendet:

runs-on: ubuntu-latest

Der Forgejo Runner muss daher ein passendes Label besitzen:

ubuntu-latest

Ein zusätzliches Label wie docker ist unkritisch, solange der Runner Jobs mit ubuntu-latest annimmt.

Forgejo Variables und Secrets

Die Deployment-Konfiguration wird nicht im Repository gespeichert. Nicht sensible Werte werden in Forgejo als Actions Variables hinterlegt:

Repo -> Settings -> Actions -> Variables

Erforderliche Variables:

FTP_SERVER

Hostname oder IP-Adresse des FTP/FTPS-Servers.

FTP_USERNAME

FTP-Benutzername.

FTP_TARGET_DIR

Zielverzeichnis aus Sicht des FTP-Benutzers.

Beispiele:

./

Wenn der FTP-Benutzer direkt im Zielordner landet.

test/

Wenn der FTP-Benutzer eine Ebene oberhalb liegt und der Zielordner test heißt.

public/test/

Wenn dieser Pfad nach dem FTP-Login sichtbar ist.

Der Wert sollte mit / enden, wenn es ein Verzeichnis ist.

Das Passwort bleibt als Actions Secret hinterlegt:

Repo -> Settings -> Actions -> Secrets

Erforderliches Secret:

FTP_PASSWORD

FTP-Passwort.

FTPS-Verhalten

Das Deployment nutzt lftp mit explizitem FTPS:

set ftp:ssl-force true
set ftp:ssl-protect-data true
set ftp:passive-mode true
set ftp:prefer-epsv false

Hintergrund: Der Webserver verlangt TLS auf dem FTP-Control-Channel. Ein vorheriger Versuch mit normalem FTP scheiterte mit:

550 SSL/TLS required on the control channel

Ein weiterer Versuch mit der SamKirkland/FTP-Deploy-Action erreichte zwar den FTPS-Login, brach aber beim Datenkanal über EPSV mit ECONNRESET ab. Deshalb nutzt der aktuelle Workflow lftp und deaktiviert EPSV bewusst:

set ftp:prefer-epsv false

Damit wird klassisches passives FTP/FTPS verwendet, was mit dem aktuellen Server funktioniert.

Sync-Verhalten

Der Workflow spiegelt den lokalen Build-Ordner auf den Server:

mirror --reverse --verbose --delete --exclude '^\.htaccess$' docs/.vitepress/dist/ "$FTP_TARGET_DIR"

Das bedeutet:

• neue Dateien aus docs/.vitepress/dist/ werden hochgeladen
• geänderte Dateien werden ersetzt
• entfernte Build-Dateien werden auch auf dem Server entfernt
• .htaccess wird nicht angefasst

Das Zielverzeichnis sollte daher exklusiv für diese Website genutzt werden. Andernfalls können Dateien gelöscht werden, die nicht mehr im VitePress-Build existieren.

.htaccess

Eine vorhandene .htaccess auf dem Server bleibt erhalten. Sie wird im Deployment explizit ausgeschlossen:

--exclude '^\.htaccess$'

Wenn die .htaccess in Zukunft bewusst versioniert und deployed werden soll, kann sie unter docs/public/.htaccess abgelegt und der Exclude im Workflow entfernt werden.

Logs

Die Logs eines Deployments sind in Forgejo sichtbar:

Repo -> Actions -> Build and Deploy -> Run anklicken -> Job anklicken

Wichtige Steps:

• Install dependencies
• Check and build website
• Install FTPS client
• Deploy website via FTPS

Wenn der Job nicht startet, ist meist kein passender Runner für ubuntu-latest online. Wenn der Job startet, aber beim Deploy fehlschlägt, ist der Step Deploy website via FTPS der relevante Log-Abschnitt.

Typische Fehler

550 SSL/TLS required on the control channel

Der Server akzeptiert kein unverschlüsseltes FTP. Der Workflow nutzt deshalb FTPS.

ECONNRESET (data socket)

Der FTPS-Control-Channel funktioniert, aber der Datenkanal wird zurückgesetzt. Beim aktuellen Setup wurde das durch lftp und deaktiviertes EPSV gelöst.

no runner matching labels

Der Forgejo Runner hat kein passendes Label oder ist offline. Der Workflow erwartet ubuntu-latest.

npm ci

Wenn dieser Schritt fehlschlägt, passen package.json und package-lock.json möglicherweise nicht zusammen. Lokal npm install ausführen, Lockfile prüfen und committen.

Release-Ablauf

Empfohlener Ablauf für Änderungen:

1. Feature-Branch erstellen
2. Änderungen lokal testen
3. npm run check ausführen
4. Branch pushen
5. Pull Request oder Compare in Forgejo prüfen
6. Nach main mergen
7. Forgejo Actions Run beobachten
8. Website im Browser prüfen

Git Remote

Aktuelles Remote-Setup:

origin ssh://git@git.jdynamics.de:222/dev/vitepress-portfolio-website.git

Nach initialem Setup reicht für normale Updates:

git push