Zum Hauptinhalt springen

Entwicklungssetup

Voraussetzungen​

  • Docker / Docker Compose
  • Node.js (siehe engines.node in package.json)
  • pnpm (siehe engines.pnpm / packageManager in package.json)
  • SQLite3
  • Inkscape (für die Übersetzung von Dokumentations-SVGs und PNG-Export; nur erforderlich, wenn Sie translate oder translate:svg ausführen)
  • bat/batcat (um eine ansprechende Version von translate:help anzuzeigen)
  • direnv (zum automatischen Laden der .env*-Dateien)

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 - Entwicklungs-Server auf Port 8666 starten (beinhaltet Vorabprüfungen)
  • pnpm build - Anwendung für die Produktion bauen (beinhaltet Vorabprüfungen)
  • pnpm lint - ESLint ausführen, um die Code-Qualität zu überprüfen
  • pnpm typecheck - TypeScript-Typüberprüfung ausführen
  • scripts/upgrade-dependencies.sh — Build-sicheres Upgrade jedes Workspace-Pakets (automatisch erkannt). Verwendet den npm-check-updates-Doctor-Modus, um nur Upgrades beizubehalten, die die typecheck/lint jedes Pakets bestehen, und macht solche rückgängig, die den Build beschädigen; führt anschließend pnpm audit / audit --fix aus und wendet (und meldet) erzwungen jeden Sicherheitsfix an, der Codeänderungen erfordert. Aktualisiert die Workspace-Lockdatei und die Browserslist. Bevorzugen Sie source ./scripts/upgrade-dependencies.sh, damit nvm auf Ihre Shell angewendet wird; verwenden Sie in CI oder Automatisierungen CI=1 oder UPGRADE_ALLOW_EXEC=1, wenn Sie die Datei direkt ausführen. Siehe auch scripts/upgrade-tools.sh nur für Node/pnpm-Tooling.
  • scripts/clean-workspace.sh - Workspace bereinigen

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

Dokumentationsskripte​

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

  • pnpm start - Dokumentationswebsite im Produktionsmodus bauen und bereitstellen (Standardport 3000)
  • pnpm start:en - Entwicklungs-Server für Dokumentation auf Englisch starten (Hot Reloading aktiviert)
  • pnpm start:fr - Entwicklungs-Server für Dokumentation im Französisch-Format starten (Hot Reloading aktiviert)
  • pnpm start:de - Entwicklungs-Server für Dokumentation im Deutsch-Format starten (Hot Reloading aktiviert)
  • pnpm start:es - Entwicklungs-Server für Dokumentation im Spanisch-Format starten (Hot Reloading aktiviert)
  • pnpm start:pt-br - Entwicklungs-Server für Dokumentation im Portugiesisch (Brasilien)-Format starten (Hot Reloading aktiviert)
  • pnpm build - Dokumentationswebsite für die Produktion bauen
  • pnpm write-translations - Übersetzbare Zeichenketten aus der Dokumentation extrahieren
  • pnpm translate - Dokumentationsdateien mithilfe von KI übersetzen (siehe Übersetzungsworkflow)
  • pnpm lint - ESLint auf Dokumentations-Quelldateien 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 - Erstellt ein Entwicklung-Docker-Image mit dem Tag wsj-br/duplistatus:devel

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 - Test-Sicherungsdaten generieren (erfordert Parameter --servers=N)
  • pnpm validate-csv-export - CSV-Exportfunktionalität überprüfen
  • pnpm test-entrypoint - Docker-Entrypoint-Skript im lokalen Entwicklungsmodus testen (siehe Testskripte)
  • pnpm take-screenshots - Erstellt Screenshots für die Dokumentation (siehe Dokumentationswerkzeuge)

Überfällige Prüfungen, Cron-Systemprüfungen und SMTP-Tests erfolgen über die laufende Anwendung und curl (siehe Test-Skripte); die alten eigenständigen pnpm-Hilfsskripte dafür wurden entfernt.