Merge pull request #1983 from openaustralia/chore/update_development_setup_and_doc

Chore/update development setup and doc

Author: ianheggie-oaf

README.md

@@ -24,10 +24,33 @@ git clone https://github.com/openaustralia/planningalerts.git
 cd planningalerts
 ```
 
+### Resetting Your Environment
+
+To force a rebuild from scratch, stopping and removing containers and volumes (including the databases):
+
+```sh
+docker compose down -v --rmi all
+# Check if this volume is "still in use" 
+docker volume rm planningalerts_gem_cache
+```
+
+If you get a `volume is in use` error, remove the container using the given id and then retry, for example:
+
+```sh
+> Error response from daemon: remove planningalerts_gem_cache: volume is in use - [98ba717d944d01976ac9074e6a1119e70d3aebd53f5d5449957324926f0bbb4b]
+
+docker rm 98ba717d944d01976ac9074e6a1119e70d3aebd53f5d5449957324926f0bbb4b
+> 98ba717d944d01976ac9074e6a1119e70d3aebd53f5d5449957324926f0bbb4b
+
+docker volume rm planningalerts_gem_cache
+```
+
 ### Setup The Database
 
 Set up the databases - `docker compose run web bin/rake db:setup`
 
+This will trigger a build if needed. You can manually trigger a build by first running - `docker compose build`
+
 ### Start the application
 
 * `docker compose up`
@@ -70,6 +93,16 @@ bin/tapioca dsl --environment=test
 
 We use Shopify's [tapioca](https://github.com/Shopify/tapioca) gem to manage all our rbi files. We **don't** use `bundle exec srb rbi ...`.
 
+### Other useful docker commands
+
+* `docker compose ps` - View running containers and their status
+* `docker compose logs [-f] [service]` - View logs for all or a specific service, add `-f` to continue watching (the up command also does this)
+* `docker compose restart web` - Restart the web container (eg when you make a change to the code)
+* `docker compose down` - Stop and remove containers (keeps volumes and images intact for quick restart)
+* `docker compose exec web bash` - Run a shell in the running container
+* `docker compose run web bin/rails console` - Run a once-off command in new container
+* `docker system prune --all` - Remove all stopped containers, orphaned images / networks, build cache etc. (Remove the -v if you want to keep your databases and gem cache)
+
 ## Deployment
 
 The code is deployed using Capistrano. To deploy to production run:

docker-compose.yml

@@ -13,10 +13,18 @@ services:
     ports:
       - "3000:3000"
     depends_on:
-      - postgres
-      - redis
-      - mailcatcher
-      - elasticsearch
+      # Required for nearly everything
+      postgres:
+        condition: service_healthy
+      # Required for rack stack and flipper initialisation abd caching
+      redis:
+        condition: service_healthy
+      # Required for logging api calls etc
+      elasticsearch:
+        condition: service_healthy
+      # Required for jobs sending email
+      mailcatcher:
+        condition: service_healthy
     command: "bin/dev"
     tty: true
 
@@ -30,9 +38,11 @@ services:
     ports:
       - "2525:25"
     depends_on:
-      - postgres
+      postgres:
+        condition: service_healthy
     user: root
     command: postfix start-fg
+    
 
   postgres:
     # Same version as used in production
@@ -51,6 +61,13 @@ services:
     environment:
       # The values below need to be the same in config/database.yml
       POSTGRES_PASSWORD: password
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres || exit 1"]
+      interval: 5s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+      # start_interval: 1s  # TODO: Uncomment after 2028 when Docker Compose 2.21+ should be widespread (introduced Dec 2023)
 
   redis:
     # TODO: Try switching to alpine variant for slimmer images
@@ -60,13 +77,27 @@ services:
       - "6379"
     volumes:
       - redis_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "redis-cli ping || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+      # start_interval: 1s  # TODO: Uncomment after 2028 when Docker Compose 2.21+ should be widespread (introduced Dec 2023)
 
   mailcatcher:
     build:
       context: .
       dockerfile: Dockerfile.mailcatcher
     ports:
       - "1080:1080"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:1080 || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+      # start_interval: 1s  # TODO: Uncomment after 2028 when Docker Compose 2.21+ should be widespread (introduced Dec 2023)
 
   elasticsearch:
     # Using version 7.17.7 in production. So matching here
@@ -79,6 +110,13 @@ services:
       - "discovery.type=single-node"
     volumes:
       - elasticsearch_data:/usr/share/elasticsearch/data
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://localhost:9200/_cluster/health || exit 1"]
+      interval: 5s
+      timeout: 10s
+      retries: 5
+      start_period: 30s
+      # start_interval: 1s  # TODO: Uncomment after 2028 when Docker Compose 2.21+ should be widespread (introduced Dec 2023)
 
 volumes:
   gem_cache: