Zum Hauptinhalt springen

Entwicklungssetup

Voraussetzungen​

  • Docker / Docker Compose
  • Node.js >=24.12.0
  • pnpm >=10.24.0 (packageManager: pnpm@10.30.3)
  • SQLite3
  • Inkscape (für die Übersetzung von Dokumentations-SVG und PNG-Exportieren; erforderlich nur, wenn Sie translate oder translate:svg ausführen)
  • bat/batcat (um eine schöne Version der translate:help einzublenden)
  • direnv (um die .env*-Dateien automatisch zu laden)

Schritte​

1. Repository klonen:​

git clone https://github.com/wsj-br/duplistatus.git
cd duplistatus

2. Abhängigkeiten installieren (Debian/Ubuntu):​

sudo apt update
sudo apt install sqlite3 git inkscape bat -y

3. Alte Node.js-Installationen entfernen (falls bereits installiert)​

sudo apt-get purge nodejs npm -y
sudo apt-get autoremove -y
sudo rm -rf /usr/local/bin/npm 
sudo rm -rf /usr/local/share/man/man1/node* 
sudo rm -rf /usr/local/lib/dtrace/node.d
rm -rf ~/.npm
rm -rf ~/.node-gyp
sudo rm -rf /opt/local/bin/node
sudo rm -rf /opt/local/include/node
sudo rm -rf /opt/local/lib/node_modules
sudo rm -rf /usr/local/lib/node*
sudo rm -rf /usr/local/include/node*
sudo rm -rf /usr/local/bin/node*

4. Node.js und pnpm installieren:​

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
npm install -g pnpm npm-check-updates doctoc

5. Direnv-Unterstützung einrichten​

Fügen Sie diese Zeilen zu Ihrer ~/.bashrc-Datei hinzu

# direnv support (apt install direnv)
eval "$(direnv hook bash)"

mit diesem Befehl:

(echo "# direnv support (apt install direnv)"; echo 'eval "$(direnv hook bash)') >> ~/.bashrc

im Repository-Basisverzeichnis ausführen:

direnv allow

Fügen Sie diese Zeilen zu Ihrer ~/.profile-Datei hinzu

# export the Bash environment (needed for code editor or AI Agents to load it).
export BASH_ENV="$HOME/.bashrc"

mit diesem Befehl:

(echo "# export the Bash environment (needed for code editor or AI Agents to load it)."; \
 echo 'export BASH_ENV="$HOME/.bashrc"') >> ~/.profile
Info

Sie müssen das Terminal neu öffnen oder möglicherweise die Code-Editor-IDE (Visual Studio Code, Cursor, Lingma, Antigravity, Zed, ...) schließen und wieder öffnen, damit diese Änderungen wirksam werden.

6. .env-Datei im Repository-Basisverzeichnis mit diesen Variablen erstellen.​

  • Sie können einen beliebigen Wert für VERSION verwenden; dieser wird automatisch aktualisiert, wenn die Entwicklungsskripte verwendet werden.

  • Verwenden Sie zufällige Passwörter für ADMIN_PASSWORD und USER_PASSWORD; diese Passwörter werden im pnpm take-screenshots-Skript verwendet.

  • Sie können den OPENROUTER_API_KEY von openrouter.ai abrufen.

    VERSION=x.x.x

    # Development user passwords
    ADMIN_PASSWORD="admin_secret"
    USER_PASSWORD="user_secret"


    # Openrouter.ai API key for translation scripts in documentation 
    OPENROUTER_API_KEY=sk-or-v1-your-key-for-translate-files

Verfügbare Skripte​

Das Projekt enthält mehrere npm-Skripte für verschiedene Entwicklungsaufgaben:

Entwicklungsskripte​

  • pnpm dev - Starten Sie den Entwicklungsserver auf Port 8666 (einschließlich Vorprüfungen)
  • pnpm build - Erstellen Sie die Anwendung für die Produktion (einschließlich Vorprüfungen)
  • pnpm lint - Führen Sie ESLint aus, um die Codequalität zu prüfen
  • pnpm typecheck - Führen Sie die TypeScript-Typprüfung aus
  • scripts/upgrade-dependencies.sh - Aktualisieren Sie alle Pakete auf die neueste Version, prüfen Sie auf Sicherheitslücken und beheben Sie diese automatisch
  • scripts/clean-workspace.sh - Bereinigen Sie den Arbeitsbereich

Hinweis: Das preinstall-Skript erzwingt automatisch pnpm als Paketmanager.

Dokumentationsskripte​

Diese Skripte müssen aus dem documentation/-Verzeichnis ausgeführt werden:

  • pnpm start - Dokumentationsseite im Produktionsmodus erstellen und bereitstellen (Port 3000 standardmäßig)
  • pnpm start:en - Dokumentations-Entwicklungsserver in Englisch starten (Hot-Reloading aktiviert)
  • pnpm start:fr - Dokumentations-Entwicklungsserver in Französisch starten (Hot-Reloading aktiviert)
  • pnpm start:de - Dokumentations-Entwicklungsserver in Deutsch starten (Hot-Reloading aktiviert)
  • pnpm start:es - Dokumentations-Entwicklungsserver in Spanisch starten (Hot-Reloading aktiviert)
  • pnpm start:pt-br - Dokumentations-Entwicklungsserver in Portugiesisch (Brasilien) starten (Hot-Reloading aktiviert)
  • pnpm build - Dokumentationsseite für Produktion erstellen
  • pnpm write-translations - Übersetzbare Zeichenfolgen aus der Dokumentation extrahieren
  • pnpm translate - Dokumentationsdateien mit KI übersetzen (siehe Übersetzungs-Workflow)
  • pnpm lint - ESLint auf Dokumentationsquelldateien ausführen

Die Entwicklungsserver (start:*) bieten Hot-Module-Replacement für schnelle Entwicklung. Der Standardport ist 3000.

Produktionsskripte​

  • pnpm build-local - Erstellen und für lokale Produktion vorbereiten (einschließlich Vor-Checks, kopiert statische Dateien in das Standalone-Verzeichnis)
  • pnpm start-local - Produktions-Server lokal starten (Port 8666, einschließlich Vor-Checks). Hinweis: Führen Sie zuerst pnpm build-local aus.
  • pnpm start - Produktions-Server starten (Port 9666)

Docker-Skripte​

  • pnpm docker:up - Docker-Compose-Stack starten
  • pnpm docker:down - Docker-Compose-Stack stoppen
  • pnpm docker:clean - Docker-Umgebung und Cache bereinigen
  • pnpm docker:devel - Ein Entwicklungs-Docker-Image mit dem Tag wsj-br/duplistatus:devel erstellen

Cron-Service-Skripte​

  • pnpm cron:start - Starten des Cron-Service im Produktionsmodus
  • pnpm cron:dev - Starten des Cron-Service im Entwicklungsmodus mit Dateiüberwachung (Port 8667)
  • pnpm cron:start-local - Starten des Cron-Service lokal zum Testen (Port 8667)

Testskripte​

  • pnpm generate-test-data - Testbackup-Daten generieren (erfordert --servers=N-Parameter)
  • pnpm show-overdue-notifications - Überfällige Benachrichtigungsinhalte anzeigen
  • pnpm run-overdue-check - Überfälligkeitsprüfung zu einem bestimmten Datum/Zeitpunkt ausführen
  • pnpm test-cron-port - Konnektivität des Cron-Service-Ports testen
  • pnpm test-overdue-detection - Logik zur Erkennung überfälliger Sicherungen testen
  • pnpm validate-csv-export - CSV-Export-Funktionalität validieren
  • pnpm set-smtp-test-config - SMTP-Testkonfiguration aus Umgebungsvariablen festlegen (siehe Testskripte)
  • pnpm test-smtp-connections - SMTP-Verbindungstyp-Kompatibilität testen (siehe Testskripte)
  • pnpm test-entrypoint - Docker-Entrypoint-Skript in lokaler Entwicklung testen (siehe Testskripte)
  • pnpm take-screenshots - Screenshots für Dokumentation erstellen (siehe Dokumentationstools)