From 477635b6ef764b2b864bb554eccd83cc27b227fd Mon Sep 17 00:00:00 2001
From: Johan Kromhout <johan.kromhout@dawn.tech>
Date: Tue, 3 Mar 2026 16:07:53 +0100
Subject: [PATCH] Clarify initial setup instructions in README

Prior to this change, the instructions for starting the environment and seeding the database were unclear.

This change provides detailed steps for initializing the database and starting the environment in separate terminals, ensuring users understand the process better.

Also fix some services not shutting down when using the stop script.
---
 core/README.md       | 13 ++++++++-----
 core/stop-dev-env.sh |  2 +-
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/core/README.md b/core/README.md
index 807b0a9..ba6db55 100644
--- a/core/README.md
+++ b/core/README.md
@@ -8,20 +8,23 @@ This repo contains a docker compose and some configuration to get you started wi
 ## Getting started
 
 ### The first time
-If you are doing this for the first time, first start the environment and then seed it:
+On first run, the `engine` service requires the database to be initialised before it can become healthy.
+Start the environment in one terminal, then run the init script in a second terminal.
 
-1. Start the environment:
+**Terminal 1** — start the environment (this will block while waiting for all services to become healthy):
 ```
-./start-dev-env.sh
+./start-dev-env.sh engine:/path/to/OpenConext-engineblock
 ```
 
-2. Once all containers are up, seed the environment:
+**Terminal 2** — once you see mariadb and engine starting in terminal 1, seed the environment (the script waits internally until they are ready before proceeding):
 ```
 ./scripts/init.sh
 ```
 
+After init completes, terminal 1 will finish and the environment is ready.
+
 ### After initialisation
-To start the environment again after the initial setup:
+To start the environment again after the initial setup, a single terminal is sufficient — engine will become healthy on its own because the database is already initialised:
 
 ```
 ./start-dev-env.sh
diff --git a/core/stop-dev-env.sh b/core/stop-dev-env.sh
index 999c454..ee25aa6 100755
--- a/core/stop-dev-env.sh
+++ b/core/stop-dev-env.sh
@@ -3,6 +3,6 @@
 # Use docker compose to start the environment but with the modified override file(s)
 echo -e "Stopping the dev environment with the following command:\n"
 
-command='docker compose --profile "*" -f docker-compose.yml down'
+command='docker compose --profile oidc --profile extras --profile invite --profile php --profile dashboard --profile sbs -f docker-compose.yml down'
 echo "$command"
 exec $command