Schnellstart — softwarefabrik.io

Voraussetzungen

Du brauchst nur drei Dinge auf deinem System:

Docker (24+) und Docker Compose v2 — prüfe mit docker --version und docker compose version.
Freier Port 8080 (Webanwendung) und Port 5432 (Postgres) — lokal gebunden, nur auf deiner Maschine erreichbar.
Ungefähr 5 GB freier Plattenplatz für Container-Images, Build-Cache und die ersten Workspaces.

Hinweis: Java, Maven oder Node musst du nicht lokal installieren — alle Builds laufen für diesen Schnellstart innerhalb der Container. Wenn du später echte Vendor-Adapter wie claudecode nutzt, brauchst du die jeweilige CLI lokal (siehe Tutorial). Für den Mock-Adapter brauchst du nichts weiter.

1. Distributions-Bundle beziehen

Die Fabrik ist ein lizenziertes Produkt — es gibt kein öffentliches Repo. Nach Kauf oder Trial-Freischaltung bekommst du das Distributions-Bundle. Öffne ein Terminal, entpacke es und wechsle hinein:

tar xzf softwarefabrik-einzelplatz.tar.gz
cd softwarefabrik

Im Bundle liegen die docker-compose.yml (Container für App und Postgres), das signierte JAR und eine Beispiel-.env. Nur mal ohne Installation schauen? Nutze die Live-Demo.

2. `.env`-Datei anlegen

Die Plattform liest beim Start eine .env-Datei mit Pflicht-Variablen. Die Datei liegt im entpackten Bundle-Verzeichnis (./softwarefabrik/.env) — sie enthält Geheimnisse, halte sie aus Versionsverwaltung und Backups heraus. Ersetze die Beispielwerte durch eigene starke Geheimnisse:

# Bootstrap-Admin (Login-Account beim ersten Start)
SOFTWAREFABRIK_ADMIN_USER=admin
SOFTWAREFABRIK_ADMIN_PASSWORD=ChangeMe-2026!

# Datenbank-Passwort (für Postgres im Container)
SOFTWAREFABRIK_DB_PASSWORD=DbSecret-2026!

# Master-Key für die Verschlüsselung von API-Keys (32 Byte, Base64)
SOFTWAREFABRIK_SECRETS_MASTER_KEY=<hier deinen Key einsetzen>

Den Master-Key generierst du mit einem Einzeiler. Auf Linux/macOS:

openssl rand -base64 32

Auf Windows (PowerShell):

[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

Wichtig: Ohne gesetztes SOFTWAREFABRIK_ADMIN_PASSWORD wird absichtlich kein Bootstrap-Admin angelegt — du kannst dich dann nicht einloggen. Schwache Defaults wie admin/admin wären ein Sicherheitsbug, deshalb verlangen wir ein bewusst gesetztes Passwort. Der Master-Key muss mindestens 32 Byte lang sein; ohne ihn startet die Plattform nicht. Ihn später zu ändern bedeutet, dass alle bisher gespeicherten API-Keys nicht mehr entschlüsselt werden — also einmal gut wählen, sichern und dann lassen.

3. Plattform starten

Starte die Container im Hintergrund:

docker compose up -d
docker compose logs -f app

Beim ersten Lauf werden die Images gezogen und die App gebaut — das dauert ca. 2–4 Minuten. Flyway läuft V1..V33 durch (~10 Sekunden). Sobald die Logs Started SoftwarefabrikApplication melden, ist die Plattform bereit.

Du kannst auch den Healthcheck pollen:

curl -f http://localhost:8080/actuator/health
# erwartet: {"status":"UP"}

Öffne nun den Browser auf http://localhost:8080.

4. Anmelden

Du landest auf der Login-Seite. Nutze die Credentials aus deiner .env:

Benutzername: admin (oder was du in SOFTWAREFABRIK_ADMIN_USER gesetzt hast)
Passwort: ChangeMe-2026! (oder dein eigener Wert)

Nach erfolgreichem Login landest du auf dem Dashboard mit Kennzahlen-Kacheln (alle stehen auf 0, was bei einer frischen Instanz richtig ist), der Liste deiner letzten Projekte und der letzten Runs.

Das Dashboard der Softwarefabrik nach dem Login — Das Dashboard nach dem Login. Der gelbe Hinweis „**Mock-Adapter aktiv**" ist gewollt — im Schnellstart läuft alles gegen den Mock, also ohne Kosten.

Hinweis: Falls die Login-Seite nicht erscheint und stattdessen die Whitelabel Error Page kommt: warte noch eine Minute (App startet noch) und lade neu. Wenn das Login-Formular kommt, das Passwort aber nicht akzeptiert wird: prüfe die Logs mit docker compose logs app | grep -i admin — meist fehlt die Env-Variable.

5. Erstes Projekt mit dem Wizard

Klick im Dashboard auf "Neues Projekt mit Assistent anlegen" oder navigiere direkt zu /wizard. Der Wizard hat vier Schritte:

Template wählen. Wähle Modernes Spring Boot Backend.
Fragen beantworten. Trage Beispielwerte ein:
- Projekttitel: Mein erstes Backend
- Vision: Ein einfacher Health-Check-Service
- Java-Version: 25
- Datenbank: H2 (kein extra Postgres nötig)
- Architektur: layered
- Sprache: Deutsch
Quality Gates auswählen. Lass den ArchUnit-Toggle an, alle anderen aus.
Zusammenfassung. Bestätige mit "Projekt anlegen" — die Seite zeigt Kosten-Schätzung und Prompt-Vorschau.

Der Projekt-Assistent mit dem Start eines neuen Entwurfs — Der **Assistent** führt dich in vier Schritten durch das erste Projekt — Zielplattform, Backend, Frontend und die passenden Fragen.

Du landest jetzt im Projekt-Editor unter /projects/<id>/edit mit allen Feldern bereits befüllt. Klick auf "Markdown-Artefakte generieren", damit die Plattform die sechs Spezifikationsdateien (PROJECT.md, INSTRUCTIONS.md, AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md, README.md) erzeugt.

Tipp: Lies die Artefakte einmal durch, bevor du den ersten Run startest — sie sind editierbar und das, was der Agent als Auftrag liest. Tippfehler oder unklare Formulierungen zeigen sich später in den Commits.

6. Run beobachten

Klicke im Projekt-Editor auf "Neuer Run". Auf der Run-Anlageseite:

Run-Titel: Skelett anlegen
Ziel: Lege das initiale Maven-Projekt mit Spring Boot, Health-Endpoint und einem ersten Smoke-Test an
Adapter: mock (deterministisch, kein API-Key nötig)
Klick auf "Run anlegen"

Der Run ist jetzt im Status DRAFT. Klick auf "Auf READY setzen", dann auf "Run starten". Du landest auf der Run-Detail-Seite und siehst:

Status-Indikator: wechselt durch die sieben Phasen INTAKE → PROMPT_ASSEMBLY → WORKSPACE_PREPARATION → EXECUTION → VALIDATION → CORRECTION → COMPLETION zum Endstand COMPLETED.
Logs (live): jede Zeile, die der Mock-Adapter ausgibt, erscheint sofort. Der Mock braucht ca. 10 Sekunden für einen kompletten Lauf.
Git-Ansicht: rechts siehst du die Commits, die der Agent gemacht hat — typischerweise "chore: initial scaffold" + "test: add smoke test".

7. Quality Gate

Nachdem der Run auf COMPLETED steht, klicke auf den Reiter "Quality Gate" (oder unten auf den Knopf "Quality Gate ausführen"). Die Plattform startet die fünf Reviewer (architecture-reviewer, hallucination-review, security, aider-review, claude-review) und zeigt das Verdict:

PASSED: alles grün, keine Findings.
WARNING: einzelne Findings, aber nichts blockierendes.
FAILED: mindestens ein blockierendes Finding (z.B. ArchUnit-Verletzung).

Pro Reviewer siehst du die Findings mit Severity, Confidence-Score und Erklärungstext. Im Schnellstart mit Mock-Adapter sollte typischerweise PASSED herauskommen — die Mock-Outputs sind so gebaut, dass sie keine echten Verstöße produzieren.

Policy-Tipp: Im strict-Modus (Default) blockiert eine WARNING bereits weitere Schritte. Im lenient-Modus laufen Folge-Phasen trotz WARNING durch. Für den ersten Schnellstart kannst du es auf lenient stellen unter /einstellungen → Quality Gate.

Der vollständige SDLC-Loop

Was du oben Schritt für Schritt durchgespielt hast, ist ein Ausschnitt aus dem vollständigen Lebenszyklus, den die Plattform iterativ durchläuft. Einmal eingerichtet, schließt sich der Kreis von selbst — jeder Durchlauf macht das Projekt ein Stück fertiger:

Planen. Ein Plan-Run analysiert das Projekt und erzeugt Planungsdateien (plans/*.md), die als Backlog erscheinen — eine priorisierte Liste konkreter Arbeitspakete.
Auswählen. Du aktivierst ein Backlog-Item als nächstes Ziel.
Bauen. Ein Build-Run arbeitet das Item auf einem eigenen Branch (sdlc/run-…) im persistenten Workspace ab — die Hauptlinie bleibt unberührt.
Selbstkorrektur. Schlägt der Build fehl (roter Test, Compile-Fehler), wiederholt der Agent automatisch mit dem Fehler-Feedback — begrenzt auf eine konfigurierbare Zahl Versuche.
Quality-Gate. Die Reviewer prüfen das Ergebnis. Der Modus ist wählbar: aus, beratend (Findings werden gezeigt, blockieren aber nicht) oder blockierend (Findings stoppen die Lieferung).
Liefern. Mit hinterlegtem Git-Remote und GitHub-Token pusht die Plattform den Branch und öffnet einen Pull-Request. Ohne Remote bleibt es bei einem lokalen Merge.
Lernen. Erkenntnisse aus dem Run fließen ins Project-Memory und stehen Folge-Runs als Kontext zur Verfügung.
Weiter. Optional schlägt die Plattform Auto-Folgevorschläge vor (ein neuer Plan-Run) — und der Loop schließt sich.

Hinweis: Plan-Run, Backlog, Branch-Strategie, Quality-Gate-Modus, Git-Remote/GitHub-Token und Auto-Folgevorschläge konfigurierst du unter /einstellungen. Im Schnellstart mit Mock-Adapter kannst du den Loop einmal trocken durchspielen; mit echten Adaptern (Schritt 8) liefert er produktive Commits.

Aufräumen

Wenn du die Plattform stoppen willst, ohne die Daten zu verlieren:

docker compose down

Dabei bleiben die Postgres-Daten im Docker-Volume erhalten. Beim nächsten docker compose up -d sind dein Account, deine Projekte und Runs wieder da.

Wenn du wirklich alles löschen willst (DB, Workspaces, Logs):

docker compose down -v
rm -rf ./workspaces

Vorsicht: Das -v-Flag löscht alle Docker-Volumes, also auch deine Datenbank. Mach das nur, wenn du wirklich neu anfangen willst.

Häufige Fragen

Port 8080 ist belegt

Setze in der .env die Variable SOFTWAREFABRIK_PORT=9090 und starte die Container neu. Alternativ stoppst du den Prozess, der 8080 belegt (häufig Tomcat oder ein anderer Spring-Boot-Prozess) — finde ihn mit lsof -i :8080.

Login-Seite akzeptiert das Passwort nicht

Prüfe, ob du das Passwort in der .env richtig geschrieben hast (keine Anführungszeichen drumherum, keine Leerzeichen). Mit docker compose logs app | grep -i admin siehst du, ob die Plattform den Bootstrap-Admin angelegt hat. Kommt statt des Logins eine Whitelabel Error Page, startet die App meist noch — eine Minute warten und neu laden.

Build dauert ewig

Der erste Build des Maven-Projekts braucht 2–4 Minuten, weil Spring-Boot-Abhängigkeiten gezogen werden. Folgende Builds sind dank Docker-Layer-Cache deutlich schneller. Mit docker compose build --pull erzwingst du einen frischen Build, falls du Verdacht auf einen kaputten Cache hast.

Wizard zeigt veraltete Versionen

Der Versions-Cache wird täglich um 03:00 aktualisiert. Bei einem frischen Setup hat er noch keine Werte und zeigt Fallback-Versionen aus dem Code. Auf /einstellungen/wizard/versions kannst du "Jetzt manuell refreshen" klicken — braucht eine Internetverbindung.

Mein Run hängt in DRAFT

Ein neuer Run ist immer im Status DRAFT. Du musst ihn erst auf READY setzen und dann den Knopf "Run starten" klicken. Diese zwei Bestätigungspunkte sind Absicht, damit nicht versehentlich Tokens verbrannt werden.

Wo liegen die Workspaces?

Standardmäßig unter ./workspaces/<run-id>/ im Bundle-Verzeichnis. Den Pfad kannst du unter /einstellungen → Workspace ändern. Jeder Run bekommt sein eigenes Verzeichnis mit eigener Git-Historie.

Betriebsmodus wählen

Bevor du mit echten Adaptern loslegst, entscheide den Betriebsmodus der Instanz. Er steuert, ob der Abo-Login (persönliches Claude-/Codex-Abo) erlaubt ist oder ob ausschließlich hinterlegte API-Keys genutzt werden. Setzbar als Setting betrieb.modus unter /einstellungen (oder per Env SOFTWAREFABRIK_BETRIEB_MODUS):

EINZELPLATZ_ABO (Default) — nutzt den Claude-/Codex-Abo-Login (persönliches Max-/Pro-Abo). Bequem für den Einzelplatz, kein API-Billing-Setup nötig.
TEAM_API_POOL — sperrt den Abo-Login und erzwingt einen hinterlegten API-Key (Team-/Pool-Abrechnung). Pflicht, sobald mehr als ein Sitz im Spiel ist, weil Abos ToS-seitig nicht auf Teams skalieren.

Hinweis: Für diesen Schnellstart mit Mock-Adapter spielt der Betriebsmodus keine Rolle — der Default EINZELPLATZ_ABO passt. Relevant wird er erst mit echten Vendor-Adaptern (nächster Schritt).

8. Weiter mit echten Adaptern

Wenn der Mock-Adapter funktioniert, sind die Vendor-Adapter dran:

→ Tutorial mit Claude Code — vollständiger Workflow gegen Anthropic.
Setup von API-Keys: /integrations in der Plattform-UI.
Container-Sandbox aktivieren: Setting execution.sandbox.variant=container in /einstellungen.

In 10 Minuten zum ersten Run.