imageforge/README.md

# ImageForge

ImageForge ist eine lokal laufende Desktop-App zur Bild-Erstellung per Prompt. Die App nutzt ein Python-Backend (FastAPI + Job-Queue) und ein Electron+React-Frontend.

Features

• Prompt + Negative Prompt
• Modellauswahl (dummy, localai, diffusion)
• Bildtyp-Presets und Stil-Presets
• Image-to-Image (Startbild + Strength)
• Dashboard (Queue, Status, Retry/Cancel, Compare)
• Preset-System (CRUD)
• Export (PNG/JPG/WEBP)
• Prompt-Versionierung (config_hash in meta.json)
• API-Key + Rollenmodell (viewer, operator, admin)
• Rate-Limit pro Client
• Health + Readiness + Metrics
• Recovery von Job-Status nach Neustart
• Storage-Governance (Retention-Cleanup)

Setup

cd imageforge
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
npm --prefix frontend install

Start

npm run dev

Für den kompletten lokalen Stack (Backend + Frontend, inkl. Healthcheck):

npm run dev:stack

Serverbetrieb

$env:IMAGEFORGE_HOST="0.0.0.0"
$env:IMAGEFORGE_PORT="8008"
$env:IMAGEFORGE_CORS_ORIGINS="http://localhost:5173"
$env:IMAGEFORGE_API_KEYS="viewerKey:viewer,opsKey:operator,adminKey:admin"
$env:IMAGEFORGE_RATE_LIMIT_PER_MIN="120"
$env:IMAGEFORGE_CONTENT_PROFILE="internal-relaxed"
$env:IMAGEFORGE_ADMIN_TOKEN="change-me"
python -m backend.app.main

Wichtige Endpunkte

• GET /health
• GET /ready
• GET /metrics
• GET /metrics/prometheus
• POST /generate
• GET /jobs
• POST /jobs/{id}/retry
• POST /jobs/{id}/cancel
• GET /dashboard/stats
• GET/POST/DELETE /presets
• POST /export
• GET/PUT /admin/settings
• POST /admin/cleanup

Security und Policy

• API-Key Header: X-ImageForge-Api-Key
• Admin Override Header: X-ImageForge-Admin-Token
• Policy Profile:
  • strict
  • internal-relaxed
• Audit-Logs:
  • policy_audit.log
  • admin_audit.log

Backup / Restore

npm run backup
npm run restore -- -Source backups\imageforge_backup_YYYYMMDD_HHMMSS

Tests

npm run test
npm run test:e2e

CI

GitHub Actions Workflow liegt in .github/workflows/ci.yml.

Optional LocalAI / Diffusion

pip install diffusers torch transformers accelerate
$env:IMAGEFORGE_LOCALAI_MODEL="stabilityai/sd-turbo"
$env:IMAGEFORGE_LOCALAI_IMAGE_TIMEOUT_SECONDS="180"
$env:IMAGEFORGE_LOCALAI_LOCAL_ONLY="1"
$env:IMAGEFORGE_ENABLE_ATTENTION_SLICING="1"

Wenn torch.cuda.is_available() auf False bleibt, ist oft eine CPU-only Torch-Build installiert. Für NVIDIA-GPU unter Windows kann eine CUDA-Build so installiert werden:

python -m pip install --upgrade --index-url https://download.pytorch.org/whl/cu121 torch torchvision torchaudio

Optional AUTOMATIC1111 Integration

ImageForge kann AUTOMATIC1111 als Provider nutzen (model = a1111).

Empfohlener Produktionspfad (Stability Matrix)

Für stabilen Betrieb auf Windows wird eine saubere, manager-gesteuerte Installation empfohlen (statt manuell gepatchter stable-diffusion-webui-Klone):

1. Stability Matrix installieren und dort eine frische WebUI-Instanz mit aktivierter API starten.
2. API-Endpunkt prüfen:

Invoke-RestMethod http://127.0.0.1:7860/sdapi/v1/sd-models

3. ImageForge auf diese Instanz zeigen (Default ist bereits 127.0.0.1:7860):

$env:IMAGEFORGE_A1111_BASE_URL="http://127.0.0.1:7860"

1. AUTOMATIC1111 lokal starten (mit API), z. B.:

webui-user.bat --api

2. Optional URL/Timeout konfigurieren:

$env:IMAGEFORGE_A1111_BASE_URL="http://127.0.0.1:7860"
$env:IMAGEFORGE_A1111_TIMEOUT_SECONDS="180"
$env:IMAGEFORGE_A1111_HEALTH_ENDPOINT="/sdapi/v1/sd-models"
$env:IMAGEFORGE_A1111_RETRY_COUNT="2"
$env:IMAGEFORGE_A1111_RETRY_BACKOFF_SECONDS="1.0"

Falls A1111 mit --api-auth user:password läuft:

$env:IMAGEFORGE_A1111_API_USER="user"
$env:IMAGEFORGE_A1111_API_PASSWORD="password"

Alternativ als ein String:

$env:IMAGEFORGE_A1111_API_AUTH="user:password"

Danach erscheint AUTOMATIC1111 in /models als verfügbar, sobald der A1111-Server erreichbar ist.

Robuster Betrieb bei A1111-Ausfällen

Wenn A1111 nicht erreichbar ist oder Fehler liefert, kann ImageForge automatisch auf andere Provider wechseln (z. B. localai, diffusion, dummy) statt den Job direkt abzubrechen.

$env:IMAGEFORGE_ENABLE_AUTO_FALLBACK="1"
$env:IMAGEFORGE_FALLBACK_MODELS="a1111,localai,diffusion,dummy"
$env:IMAGEFORGE_FALLBACK_TIMEOUT_SECONDS="90"
$env:IMAGEFORGE_FALLBACK_MAX_STEPS="24"

• IMAGEFORGE_ENABLE_AUTO_FALLBACK: 1 aktiviert automatische Umschaltung.
• IMAGEFORGE_FALLBACK_MODELS: Priorisierte Reihenfolge der Fallback-Provider.
• IMAGEFORGE_FALLBACK_TIMEOUT_SECONDS: Kürzerer Timeout pro Fallback-Versuch.
• IMAGEFORGE_FALLBACK_MAX_STEPS: Deckel für Steps bei Fallback, um Laufzeit zu reduzieren.

Stack-Readiness prüfen

Nach dem Start von Backend und A1111:

./scripts/healthcheck-stack.ps1 -RequireA1111

Das Skript validiert /health, /ready, /models und optional die A1111-API selbst.

Troubleshooting

• Falls Desktop-Build auf Windows an Symlink-Rechten scheitert: Entwickler-Modus oder Admin-Rechte aktivieren.
• Logs: app.log, policy_audit.log, admin_audit.log.