This page takes you from "repo cloned" to "first run completed" in ten minutes. It is deliberately click-by-click and assumes nothing. If you want to go deeper afterwards, see the introduction or the tutorial.
You need just three things on your machine:
docker --version and docker compose version.claudecode, you'll need that CLI locally (see the tutorial). For the mock adapter, nothing extra is needed.Open a terminal, clone the platform repo and enter the directory:
git clone https://github.com/janda-io/SoftwareFabrik.git cd SoftwareFabrik
In the repo root you'll find docker-compose.yml (defines the containers for app and Postgres), the app/ directory (Spring Boot source) and the html/ directory with this documentation.
.env fileThe platform reads a .env file with mandatory variables on startup. The file lives at the repo root (./SoftwareFabrik/.env) and is not committed — it holds secrets that don't belong in the repository.
Create the file with the following content. Replace the example values with strong secrets of your own:
# Bootstrap admin (login account on first start) SOFTWAREFABRIK_ADMIN_USER=admin SOFTWAREFABRIK_ADMIN_PASSWORD=ChangeMe-2026! # Database password (for Postgres in the container) SOFTWAREFABRIK_DB_PASSWORD=DbSecret-2026! # Master key for encrypting API keys (32 bytes, base64) SOFTWAREFABRIK_SECRETS_MASTER_KEY=<paste your key here>
Generate the master key with a one-liner. On Linux/macOS:
openssl rand -base64 48
On Windows (PowerShell):
[Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))
SOFTWAREFABRIK_ADMIN_PASSWORD, the platform deliberately does not create a bootstrap admin — you won't be able to log in. Weak defaults like admin/admin would be a security bug, so we require an explicitly set password. Changing the master key later means previously stored API keys can no longer be decrypted — pick once, then leave it alone.Start the containers in the background:
docker compose up -d
The first run pulls the images and builds the app — this takes about 2–4 minutes. Watch progress with docker compose logs -f app. As soon as the logs report Started Application in ..., the platform is ready.
You can also poll the health endpoint:
curl -f http://localhost:8080/actuator/health
# expects: {"status":"UP"}
Now open your browser at http://localhost:8080.
You land on the login page. Use the credentials from your .env:
admin (or whatever you set in SOFTWAREFABRIK_ADMIN_USER)ChangeMe-2026! (or your own value)After a successful login you reach the dashboard with KPI tiles (everything is at zero, which is correct on a fresh instance), a list of your most recent projects and your most recent runs.
docker compose logs app | grep -i admin — usually the env variable is missing.From the dashboard click "New project with assistant" or navigate directly to /wizard. The wizard has four steps:
You now land in the project editor at /projects/<id>/edit with all fields pre-filled. Click "Generate Markdown artifacts" to have the platform produce the six specification files (PROJECT.md, INSTRUCTIONS.md, AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md, README.md).
In the project editor click "New run". On the run-creation page:
The run is now in status DRAFT. Click "Move to READY", then "Start run". You land on the run detail page and see:
RUNNING through the phases (PROMPT_ASSEMBLY, WORKSPACE_PREPARATION, EXECUTION, VALIDATION, COMPLETION) to the final state COMPLETED.Once the run reaches COMPLETED, click the "Quality gate" tab (or the "Run quality gate" button at the bottom). The platform launches the reviewers and shows the verdict:
For each reviewer you see findings with severity, confidence score and explanation. In the quickstart with the mock adapter you should typically get PASSED — mock outputs are designed not to trigger real violations.
To stop the platform without losing data:
docker compose down
That keeps Postgres data in the Docker volume. The next docker compose up -d brings your account, projects and runs back.
To wipe everything (DB, workspaces, logs):
docker compose down -v rm -rf ./workspaces
-v flag deletes all Docker volumes, including your database. Only do this if you really want to start over.Set SOFTWAREFABRIK_PORT=9090 in .env and restart. Alternatively, stop the process holding 8080 (often Tomcat or another Spring Boot process) using lsof -i :8080.
Check that the password in .env is spelled correctly (no quotes, no leading/trailing whitespace). With docker compose logs app | grep -i admin you can see whether the platform created the bootstrap admin.
The first Maven build takes 2–4 minutes pulling Spring Boot dependencies. Subsequent builds are much faster thanks to the Docker layer cache. Use docker compose build --pull to force a clean build if you suspect a corrupted cache.
The version cache refreshes daily at 03:00. On a fresh setup it has no values yet and shows fallback versions from the code. At /einstellungen/wizard/versions you can hit "Refresh now" — needs an internet connection.
A new run is always in DRAFT. You first need to move it to READY and then click the "Start run" button. Two confirmation points by design — to prevent accidentally burning tokens.
By default under ./workspaces/<run-id>/ in the repo root. You can change the path at /einstellungen → Workspace. Each run gets its own directory with its own Git history.