From f57edd4d3ba481791d4562e8688b8b09544fa213 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A2u=20Cao?= <raucao@kosmos.org>
Date: Sat, 2 Mar 2024 16:57:07 +0100
Subject: [PATCH] Update README to account for Docker Compose everywhere

---
 README.md | 46 ++++++++++++++++++++++++++++------------------
 1 file changed, 28 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 564b833..13e20ac 100644
--- a/README.md
+++ b/README.md
@@ -14,8 +14,10 @@ so:
 
 1. Make sure [Docker Compose is installed][1] and Docker is running (included in
    Docker Desktop)
-3. Run `docker compose up` and wait until 389ds announces its successful start
-   in the log output
+3. Run `docker compose up --build` and wait until all services have started
+   (389ds might take an extra minute to be ready). This will take a while when
+   running for the first time, so you might want to do something else in the
+   meantime.
 4. `docker-compose exec ldap dsconf localhost backend create --suffix="dc=kosmos,dc=org" --be-name="dev"`
 5. `docker compose run web rails ldap:setup`
 6. `docker compose run web rails db:setup`
@@ -28,38 +30,44 @@ have the password "user is user".
 
 ### Rails app
 
+_Note: when using Docker Compose, prefix the following commands with `docker-compose
+run web`._
+
 Installing dependencies:
 
     bundle install
     yarn install
 
-Setting up local database (SQLite):
+Migrating the local database (after schema changes):
 
-    bundle exec rails db:create
     bundle exec rails db:migrate
 
-Running the dev server and auto-building CSS files on change:
+Running the dev server, and auto-building CSS files on change _(automatic with Docker Compose)_:
 
     bin/dev
 
-Running the background workers (requires Redis):
+Running the background workers (requires Redis) _(automatic with Docker Compose)_:
 
     bundle exec sidekiq -C config/sidekiq.yml
 
-Running all specs:
+Running the test suite:
 
     bundle exec rspec
 
-### Docker (Compose)
+Running the test suite with Docker Compose requires overriding the Rails
+environment:
 
-There is a working Docker Compose config file, which define a number of services including
-an app server for Rails as well as a local 389ds (LDAP) server.
+    docker-compose run -e "RAILS_ENV=test" web rspec
 
-For Rails developers, you probably just want to start the LDAP server: `docker-compose up ldap`, 
-listening on port 389 on your machine. 
+### Docker Compose
 
-You can pick and choose your services adding them by name (listed in `docker-compose.yml`) at 
-the end of the docker compose command. eg. `docker compose up ldap redis`
+Services/containers are configured in `docker-compose.yml`.
+
+You can run services selectively, for example if you want to run the Rails app
+and test suite on the host machine. Just add the service names of the
+containers you want to run to the `up` command, like so:
+
+    docker-compose up ldap redis
 
 #### LDAP server
 
@@ -76,13 +84,15 @@ Now you can seed the back-end with data using this Rails task:
 The setup task will first delete any existing entries in the directory tree
 ("dc=kosmos,dc=org"), and then create our development entries.
 
-Note that all 389ds data is stored in `tmp/389ds`. So if you want to start over
-with a fresh installation, delete both that directory as well as the container.
+Note that all 389ds data is stored in the `389ds-data` volume. So if you want
+to start over with a fresh installation, delete both that volume as well as the
+container.
 
-#### Minio / RS
+#### Minio / remoteStorage
 
 If you want to run remoteStorage accounts locally, you will have to create the
-respective bucket first:
+respective bucket first. With the `minio` container running (run by default
+when using Docker Compose), follow these steps:
 
 * `docker compose up web redis minio liquor-cabinet`
 * Head to http://localhost:9001 and log in with user `minioadmin`, password