# Lokale Installation und erster Start

## Bereich

- Route: keine direkte App-Route, das ist die Startanleitung vor dem ersten Öffnen
- Zweck: Nexus Core lokal aus ZIP starten, ohne Docker und ohne Server-Installation

## Für wen diese Anleitung gedacht ist

Diese Anleitung ist für Tester und lokale Nutzer gedacht, die Nexus Core zum ersten Mal auf ihrem eigenen Windows-PC starten wollen.

Der Fokus liegt bewusst auf:

- lokaler ZIP-Installation
- lokaler Python-Umgebung
- automatischer Datenbank-Erstellung beim ersten Start
- einfachem Start ohne Docker

## Was du vorab brauchst

Vor dem ersten Start sollten diese Punkte erfüllt sein:

1. Ein Windows-PC mit Zugriff auf den entpackten Nexus-Core-Ordner
2. Eine installierte Python-Version
3. Eine funktionierende Internetverbindung für den ersten Paket-Download
4. Schreibrechte im App-Ordner, damit virtuelle Umgebung, Cache und Datenbank angelegt werden können

## Python-Voraussetzung

Nexus Core benötigt lokal Python, weil die App als Flask-Anwendung mit lokaler virtueller Umgebung läuft.

### Empfohlene Python-Version

- Python 3.11 oder neuer

### Wichtig bei der Installation

Beim Installieren von Python unter Windows unbedingt darauf achten:

- `Add Python to PATH` aktivieren
- die Standard-Installation für den aktuellen Benutzer ist in der Regel ausreichend

## ZIP-Datei entpacken

1. Die erhaltene Nexus-Core-ZIP in einen lokalen Ordner kopieren.
2. Die ZIP vollständig entpacken.
3. Den entpackten Hauptordner an einen festen Platz legen, zum Beispiel:

```text
C:\Nexus-Core-App
```

oder

```text
D:\Nexus Core\Nexus-Core-App
```

4. Die App nicht direkt aus der ZIP heraus starten.

## Ordner, die nach dem ersten Start automatisch entstehen

Beim ersten Start legt Nexus Core selbst weitere lokale Arbeitsordner an, zum Beispiel:

- `.venv/` für die Python-Umgebung
- `instance/` für lokale Daten
- `instance/filament_manager.sqlite3` für die lokale Datenbank
- Cache- und Download-Dateien für Bilder, Datenblätter oder Hilfsdaten

Die Datenbank wird automatisch erstellt, wenn noch keine vorhanden ist.

## Schnellstart unter Windows

### Empfohlener Startweg

1. Den entpackten App-Ordner öffnen.
2. Die Datei `start_nexus_core_windows.bat` per Doppelklick starten.
3. Warten, bis das Startfenster die Python-Umgebung vorbereitet hat.
4. Danach öffnet sich die App lokal im Browser.

### Was das Startskript automatisch macht

Das Windows-Startskript übernimmt beim Start:

1. Update-Prüfung vor dem Start
2. Anlegen der lokalen virtuellen Umgebung, falls sie noch fehlt
3. Installation der benötigten Python-Pakete
4. Start von `run.py`

## Manueller Start für Support oder Fehleranalyse

Wenn der automatische Start nicht funktioniert, kann die App auch manuell gestartet werden.

### Schritt 1: Terminal im App-Ordner öffnen

Beispiel:

```powershell
cd C:\Nexus-Core-App
```

### Schritt 2: Virtuelle Umgebung anlegen

```powershell
py -3 -m venv .venv
```

### Schritt 3: Virtuelle Umgebung aktivieren

```powershell
.venv\Scripts\activate
```

### Schritt 4: Abhängigkeiten installieren

```powershell
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

### Schritt 5: App starten

```powershell
python run.py
```

## Was beim ersten Start passiert

Beim ersten erfolgreichen Start:

1. wird geprüft, ob eine lokale Datenbank vorhanden ist
2. wird die Datenbank bei Bedarf automatisch angelegt
3. werden notwendige Migrationen ausgeführt
4. werden lokale Standardwerte, Einstellungen und Hilfsdaten vorbereitet
5. wird die App im Browser auf der lokalen Adresse geöffnet

Typische lokale Adresse:

```text
http://127.0.0.1:5000
```

## Schritt-für-Schritt für neue Tester

### Schritt 1: Python prüfen

1. `Windows-Terminal` oder `PowerShell` öffnen.
2. `python --version` oder `py --version` eingeben.
3. Prüfen, ob Python gefunden wird.

### Schritt 2: ZIP entpacken

1. Nexus-Core-ZIP mit Rechtsklick entpacken.
2. Einen festen Zielordner wählen.
3. Sicherstellen, dass alle Dateien vollständig entpackt sind.

### Schritt 3: App starten

1. In den App-Ordner wechseln.
2. `start_nexus_core_windows.bat` starten.
3. Den ersten Paket- und Setup-Lauf abwarten.

### Schritt 4: Browser prüfen

1. Warten, bis sich die lokale App-Adresse öffnet.
2. Dashboard und Navigation prüfen.
3. Kurz testen, ob `Settings`, `Wiki` und `Globale Filamente` erreichbar sind.

### Schritt 5: Datenbank-Erstellung prüfen

1. Im App-Ordner den `instance/`-Bereich prüfen.
2. Kontrollieren, ob eine lokale Datenbankdatei angelegt wurde.
3. Danach erst mit echten Daten arbeiten oder Backups einspielen.

## Beispiel für einen lokalen Testaufbau

```text
Installationsordner: D:\Nexus Core\Nexus-Core-App
Python: 3.14
Startdatei: start_nexus_core_windows.bat
Lokale URL: http://127.0.0.1:5000
Datenbank: instance/filament_manager.sqlite3
```

## Typische Fehlerbilder und Lösungen

### Python wird nicht gefunden

Ursache:

- Python ist nicht installiert
- Python wurde ohne PATH-Eintrag installiert

Lösung:

1. Python installieren oder reparieren
2. `Add Python to PATH` aktivieren
3. Terminal neu öffnen

### Die App startet, das Fenster schließt sich aber wieder

Ursache:

- Fehler in der Python-Umgebung
- fehlende Pakete
- defekter Startpfad

Lösung:

1. App einmal manuell über PowerShell starten
2. die Ausgabe lesen
3. fehlende Pakete oder Pfadfehler beheben

### Der Browser zeigt keine Seite

Ursache:

- App-Prozess wurde nicht erfolgreich gestartet
- Port 5000 ist blockiert oder wird schon genutzt

Lösung:

1. prüfen, ob das Terminal noch läuft
2. Start erneut versuchen
3. notfalls `python run.py` manuell ausführen

### Die Datenbank fehlt nach dem Start

Ursache:

- Start wurde vorzeitig abgebrochen
- keine Schreibrechte im App-Ordner

Lösung:

1. App-Ordner in einen beschreibbaren lokalen Pfad verschieben
2. Start erneut ausführen
3. prüfen, ob `instance/` angelegt wird

## Wichtige Hinweise für Updates

- Die App soll lokal vollständig entpackt vorliegen.
- Alte ZIPs nicht einfach über eine laufende Instanz kopieren.
- Vor größeren Updates immer ein lokales Backup der Datenbank erstellen.
- Die lokale Installation ist aktuell der Standardweg. Docker ist bewusst noch nicht Teil dieser Anleitung.

## Screenshot-Pflicht für diesen Artikel

1. Entpackter Nexus-Core-Ordner im Explorer
2. Erststart über `start_nexus_core_windows.bat`
3. Erfolgreich geöffnete lokale App im Browser
