Docker use ephemeral ports

Author: lcreid

CONTRIBUTING.md

@@ -76,7 +76,7 @@ cd demo
 bundle exec rails test:all # or test:system
 ```
 
-The [Docker development environment](#using-docker compose) appears to generate screenshots that are the same as what GitHub generates.
+The [Docker development environment](#developing-with-docker) appears to generate screenshots that are the same as what GitHub generates.
 
 Finally, maintainers may sometimes push changes directly to `main` or use other workflows to update the code. If pushing to `main` generates a commit for screenshot changes, please consider reverting your change immediately by executing the above `pull` and `revert` and another `push`, for the sanity of users who are using the edge (`main` branch) version of the gem. At any rate, review the changes promptly and use your judgement.
 

DOCKER.md

@@ -12,12 +12,10 @@ Put your personal and OS-specific configuration in a `compose.override.yml` file
 The following instructions work for an Ubuntu host, and will probably work for other common Linux distributions. Add a `compose.override.yml` in the local directory, that looks like this:
 
 ```compose.override.yml
-version: '3.3'
-
 # https://blog.giovannidemizio.eu/2021/05/24/how-to-set-user-and-group-in-docker compose/
 
 services:
-  shell:
+  web:
     # You have to set the user and group for this process, because you're going to be
     # creating all kinds of files from inside the container, that need to persist
     # outside the container.
@@ -50,23 +48,45 @@ docker compose up -d
 You may need to install or update the gems:
 
 ```bash
-docker compose exec -it shell bundle install
+docker compose exec web bundle install
 ```
 
 To get a shell in the container:
 
 ```bash
-docker compose exec -it shell /bin/bash
+docker compose exec web /bin/bash
+```
+
+Once in the shell, run tests:
+
+```bash
+bundle exec rake test
 ```
 
-Once in the shell:
+Run the demo app and browse to it:
+
+```bash
+cd demo
+bin/dev
+```
+
+On the host, not the Docker container, get the port number(s) you can use in the browser to access the test app running in the Docker container:
+
+```bash
+docker compose port web 3001 | cut -d: -f 2 # Browser
+docker compose port web 7900 | cut -d: -f 2 # To watch the browser execute system tests.
+```
+
+Browse to `localhost:<port number from above>`.
+
+Run system tests:
 
 ```bash
 cd demo
 bundle exec rails test:system
 ```
 
-Note that this system test approach is highly experimental and has some rough edges. The docker compose file and/or steps to run system tests may change. The tests currently fail, because the files with which they're being compared were generated on a Mac, but the Docker containers are running Linux.
+Note that this system test approach is highly experimental and has some rough edges. The docker compose file and/or steps to run system tests may change.
 
 ## Troubleshooting Docker
 

compose.yml

@@ -3,7 +3,7 @@
 # And:
 # https://medium.com/@retrorubies/chrome-as-a-service-for-rails-testing-b1a45e70fec1
 services:
-  shell:
+  web:
     image: lenchoreyes/jade:rails-app-${RUBY_VERSION:-3.3}-sqlite-${DISTRO:-bookworm}
     stdin_open: true
     tty: true
@@ -16,8 +16,8 @@ services:
       - TEST_APP_HOST=shell
       - TEST_APP_PORT=3001
     ports:
-      - "3000:3000"
-      - "3001:3001"
+      - "3000"
+      - "3001"
     command: /bin/bash
 
   selenium:
@@ -30,6 +30,4 @@ services:
     environment:
       - LANG=en_CA.UTF-8
     ports:
-      - '4444:4444'
-      - '5900:5900'
-      - '7900:7900'
+      - "7900"