mindnet_obsidian/docs/05_Installation_Deployment.md

Mindnet Causal Assistant - Installation & Deployment

Version: 1.0.0
Stand: 2025-01-XX
Zielgruppe: Administratoren, Entwickler, Erst-Installation

---

Inhaltsverzeichnis

1. Voraussetzungen
2. Installation
3. Deployment
4. Konfiguration
5. Upgrade
6. Troubleshooting

---

Voraussetzungen

System-Anforderungen

• Betriebssystem: Windows, macOS, Linux
• Obsidian: Desktop Version (0.15.0 oder höher)
• Node.js: LTS Version (18+ empfohlen) - nur für Entwicklung
• Git: Für Repository-Zugriff (nur für Entwicklung)

Obsidian-Einstellungen

• Community Plugins: Aktiviert
• Restricted Mode: Deaktiviert (für lokale Plugins)
• Safe Mode: Deaktiviert (für Plugin-Loading)

---

Installation

Option 1: Lokale Installation (Entwicklung)

Für Entwickler, die am Plugin arbeiten:

Schritt 1: Repository klonen

git clone <repository-url> mindnet_obsidian
cd mindnet_obsidian

Schritt 2: Dependencies installieren

npm install

Schritt 3: Build

# Development Build (Watch Mode)
npm run dev

# Oder Production Build
npm run build

Schritt 4: Deployment in Vault

Windows (PowerShell):

npm run deploy:local
# oder
powershell -ExecutionPolicy Bypass -File scripts/deploy-local.ps1

Manuell:

1. Erstelle Plugin-Ordner: <vault>/.obsidian/plugins/mindnet-causal-assistant/
2. Kopiere Dateien:
   • main.js → Plugin-Ordner
   • manifest.json → Plugin-Ordner
   • Optional: styles.css → Plugin-Ordner (falls vorhanden)

Schritt 5: Plugin aktivieren

1. Öffne Obsidian
2. Settings → Community Plugins
3. Aktiviere "Mindnet Causal Assistant"
4. Plugin sollte jetzt geladen sein

Option 2: Community Plugin Installation (Zukunft)

Für Endnutzer (wenn Plugin im Community Store verfügbar):

1. Öffne Obsidian
2. Settings → Community Plugins
3. Browse → Suche "Mindnet Causal Assistant"
4. Install → Enable

---

Deployment

Lokales Deployment (Entwicklung)

Automatisches Deployment (Windows)

PowerShell-Script: scripts/deploy-local.ps1

# Script kopiert main.js, manifest.json nach Vault Plugin-Ordner
# Vault-Pfad muss in Script konfiguriert sein

Verwendung:

npm run deploy:local

Manuelles Deployment

Schritte:

1. Build ausführen: npm run build
2. Plugin-Ordner erstellen: <vault>/.obsidian/plugins/mindnet-causal-assistant/
3. Dateien kopieren:
   • main.js
   • manifest.json
   • Optional: styles.css
4. Obsidian Plugin reload (disable/enable)

Production Deployment

Release-Prozess

Schritt 1: Version bumpen

npm version patch|minor|major

Ergebnis:

• manifest.json Version wird aktualisiert
• package.json Version wird aktualisiert
• versions.json Eintrag wird hinzugefügt

Schritt 2: Build

npm run build

Ergebnis:

• main.js wird erstellt (minified)
• TypeScript-Check wird ausgeführt

Schritt 3: Git Commit

git add manifest.json versions.json package.json
git commit -m "Release v1.0.1"
git tag v1.0.1
git push origin main --tags

Schritt 4: GitHub Release

1. Erstelle Release auf GitHub
2. Tag: v1.0.1 (ohne v Prefix)
3. Title: v1.0.1
4. Description: Changelog
5. Assets: Upload main.js, manifest.json, optional styles.css

---

Konfiguration

Erste Konfiguration

Nach der Installation müssen Konfigurationsdateien im Vault vorhanden sein:

Standard-Pfade

_system/
  dictionary/
    edge_vocabulary.md
    graph_schema.md
    interview_config.yaml
    chain_roles.yaml
    chain_templates.yaml
    analysis_policies.yaml

Plugin-Settings

1. Öffne Settings → Community Plugins → Mindnet Causal Assistant

2. Prüfe Pfad-Settings:

   • edgeVocabularyPath: _system/dictionary/edge_vocabulary.md
   • graphSchemaPath: _system/dictionary/graph_schema.md
   • interviewConfigPath: _system/dictionary/interview_config.yaml
   • chainRolesPath: _system/dictionary/chain_roles.yaml
   • chainTemplatesPath: _system/dictionary/chain_templates.yaml

3. Passe Pfade an (falls abweichend)

Config-Dateien erstellen

Falls Config-Dateien fehlen:

1. Erstelle Ordner: _system/dictionary/
2. Erstelle Config-Dateien (siehe Administratorhandbuch)
3. Plugin lädt Configs automatisch beim Start

Minimal-Beispiele:

edge_vocabulary.md:

# Edge Vocabulary

> [!edge-type] causes
> Canonical: causes
> Aliases: ausgelöst_durch

interview_config.yaml:

version: "1.0"
frontmatter_whitelist: []
profiles:
  - key: experience_basic
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: ""
    steps: []

chain_roles.yaml:

version: "1.0"
roles:
  causal:
    edge_types:
      - causes

chain_templates.yaml:

version: "1.0"
defaults:
  matching:
    required_links: false
templates: []

Verifikation

Plugin-Status prüfen:

1. Öffne DevTools (Ctrl+Shift+I / Cmd+Option+I)
2. Prüfe Console-Logs:
   • Vocabulary auto-loaded
   • Interview config auto-loaded
   • Chain roles loaded
   • Chain templates loaded

Commands testen:

1. Command Palette (Ctrl+P / Cmd+P)
2. Suche "Mindnet"
3. Commands sollten verfügbar sein

---

Upgrade

Upgrade-Prozess

Option 1: Lokales Upgrade (Entwicklung)

Schritte:

1. Repository aktualisieren:

   git pull origin main
   

2. Dependencies aktualisieren (falls nötig):

   npm install
   

3. Build:

   npm run build
   

4. Deployment:

   npm run deploy:local
   

5. Obsidian Plugin reload (disable/enable)

Option 2: Community Plugin Upgrade (Zukunft)

Automatisch:

• Obsidian prüft automatisch auf Updates
• Settings → Community Plugins → Updates
• Update Button klicken

Manuell:

• Plugin deinstallieren → neu installieren

Config-Migration

Bei größeren Version-Updates:

1. Backup erstellen:

   • Config-Dateien sichern
   • Vault-Backup erstellen

2. Changelog prüfen:

   • Breaking Changes beachten
   • Config-Format-Änderungen prüfen

3. Configs aktualisieren:

   • Neue Felder hinzufügen (falls nötig)
   • Deprecated Felder entfernen

4. Plugin neu laden:

   • Plugin disable/enable
   • Console-Logs prüfen

---

Troubleshooting

Plugin lädt nicht

Symptom: Plugin erscheint nicht in Settings oder zeigt Fehler.

Lösung:

1. Prüfe Obsidian-Version (min. 0.15.0)
2. Prüfe manifest.json Syntax
3. Prüfe main.js Existenz im Plugin-Ordner
4. Prüfe Console-Logs (DevTools F12)
5. Obsidian neustarten
6. Plugin disable/enable

Config wird nicht geladen

Symptom: Console zeigt "Config not found" oder Fehler.

Lösung:

1. Prüfe Pfad in Settings
2. Prüfe Datei-Existenz im Vault
3. Prüfe Datei-Berechtigungen
4. Prüfe YAML-Syntax (für YAML-Dateien)
5. Prüfe Console-Logs für Details

Build-Fehler

Symptom: npm run build schlägt fehl.

Lösung:

1. Prüfe Node.js-Version (node --version)
2. Dependencies neu installieren: npm install
3. Prüfe TypeScript-Fehler: npm run build
4. Prüfe tsconfig.json Syntax
5. Prüfe esbuild.config.mjs Syntax

Deployment-Fehler

Symptom: deploy-local.ps1 schlägt fehl.

Lösung:

1. Prüfe Vault-Pfad im Script
2. Prüfe PowerShell Execution Policy:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

3. Manuelles Deployment versuchen
4. Prüfe Plugin-Ordner-Berechtigungen

Live-Reload funktioniert nicht

Symptom: Config-Änderungen werden nicht übernommen.

Lösung:

1. Prüfe Datei-Pfad (muss exakt mit Settings übereinstimmen)
2. Warte auf Debounce (200ms)
3. Manuelles Reload über Command
4. Plugin neu laden (disable/enable)

Commands erscheinen nicht

Symptom: Commands sind nicht im Command Palette verfügbar.

Lösung:

1. Prüfe Plugin-Status (aktiviert?)
2. Prüfe Console-Logs für Fehler
3. Obsidian neustarten
4. Command Palette neu öffnen (Ctrl+P)

---

Bekannte Probleme

Windows: PowerShell Execution Policy

Problem: deploy-local.ps1 wird blockiert.

Lösung:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS/Linux: Permissions

Problem: Plugin-Ordner kann nicht erstellt werden.

Lösung:

• Prüfe Vault-Ordner-Berechtigungen
• Manuell Plugin-Ordner erstellen

Obsidian: Restricted Mode

Problem: Plugin wird nicht geladen.

Lösung:

• Settings → Community Plugins → Restricted Mode deaktivieren
• Für lokale Plugins erforderlich

---

Best Practices

Entwicklung

1. Watch Mode verwenden:

   npm run dev
   

   • Automatisches Rebuild bei Änderungen
   • Source Maps für Debugging

2. Tests ausführen:

   npm run test
   

   • Vor jedem Commit
   • Vor jedem Release

3. Linting:

   npm run lint
   

   • Code-Qualität prüfen
   • Vor jedem Commit

Deployment

1. Backup erstellen:

   • Vor jedem Deployment
   • Config-Dateien sichern

2. Staging testen:

   • Test-Vault verwenden
   • Vor Production-Deployment

3. Versionierung:

   • SemVer verwenden
   • Changelog führen

Wartung

1. Regelmäßige Updates:

   • Dependencies aktualisieren
   • Obsidian API Updates prüfen

2. Monitoring:

   • Console-Logs prüfen
   • User-Feedback sammeln

3. Dokumentation:

   • Änderungen dokumentieren
   • Breaking Changes hervorheben

---

Weitere Ressourcen

• Benutzerhandbuch: Endnutzer-Workflows
• Administratorhandbuch: Konfiguration und Wartung
• Entwicklerhandbuch: Code-Struktur und Erweiterungen
• Architektur-Dokumentation: System-Übersicht

---

Ende der Installation & Deployment Anleitung