Update instructions on usage of docker compose (#1256)

Specify a project name, which will namespace the containers and make it easier to develop on multiple branches.

.github/workflows/main.yml

@@ -19,11 +19,11 @@ jobs:
 
       - name: Build docker image
         run: |
-          docker-compose -f docker-compose.test.yml build cms_test
+          docker compose -p cms -f docker-compose.test.yml build testcms
 
       - name: Run tests
         run: |
-          docker-compose -f docker-compose.test.yml run --rm cms_test
+          docker compose -p cms -f docker-compose.test.yml run --rm testcms
 
       - uses: codecov/codecov-action@v3
         with:

Dockerfile

@@ -49,7 +49,7 @@ RUN sudo python3 setup.py install
 
 RUN sudo python3 prerequisites.py --yes --cmsuser=cmsuser install
 
-RUN sudo sed 's|/cmsuser:your_password_here@localhost:5432/cmsdb"|/postgres@cms_test_db:5432/cmsdbfortesting"|' ./config/cms.conf.sample \
+RUN sudo sed 's|/cmsuser:your_password_here@localhost:5432/cmsdb"|/postgres@testdb:5432/cmsdbfortesting"|' ./config/cms.conf.sample \
     | sudo tee /usr/local/etc/cms-testdb.conf
 
 ENV LANG C.UTF-8

docker-compose.test.yml

 version: "3.3"
 
 services:
-  cms_test_db:
-    container_name: cms_test_db
+  testdb:
     image: postgres
     environment:
       POSTGRES_HOST_AUTH_METHOD: trust
 
-  cms_test:
-    container_name: cms_test
+  testcms:
     build: .
     depends_on:
-      - "cms_test_db"
+      - "testdb"
     environment:
       CMS_CONFIG: /usr/local/etc/cms-testdb.conf
       # Could be removed in the future, see:
@@ -22,14 +20,14 @@ services:
       - "./codecov:/home/cmsuser/cms/codecov"
     privileged: true
     command: >
-      wait-for-it cms_test_db:5432 -- sh -c "
-      dropdb --host=cms_test_db --username=postgres cmsdbfortesting ;
-      createdb --host=cms_test_db --username=postgres cmsdbfortesting ;
+      wait-for-it testdb:5432 -- sh -c "
+      dropdb --host=testdb --username=postgres cmsdbfortesting ;
+      createdb --host=testdb --username=postgres cmsdbfortesting ;
       cmsInitDB ;
       sudo chown cmsuser:cmsuser ./codecov ;
       pytest --cov . --cov-report xml:codecov/unittests.xml ;
-      dropdb --host=cms_test_db --username=postgres cmsdbfortesting ;
-      createdb --host=cms_test_db --username=postgres cmsdbfortesting ;
+      dropdb --host=testdb --username=postgres cmsdbfortesting ;
+      createdb --host=testdb --username=postgres cmsdbfortesting ;
       cmsInitDB ;
       cmsRunFunctionalTests -v --coverage codecov/functionaltests.xml ;
       "

docs/Docker image.rst

@@ -6,29 +6,53 @@ easily get an instance of CMS running locally with all the necessary
 dependencies. We also provide a :gh_blob:`docker-compose.test.yml` files that
 uses said docker image to run the tests.
 
+Make sure that you have a recent version of Docker installed, as well as Docker
+Compose.
+
 .. _docker-image_running-tests:
 
 Running tests
 =============
 
-First you need to build the image:
+First you need to build the docker image, then you use it to run the tests.
+
+.. note::
+
+    The ``-p`` flag is used as a namespace for the containers that will be
+    created. When you're running tests on a separate branch, it can be useful to
+    include the branch name there, to avoid any conflict. (You can also omit the
+    flag and specify the name via the ``COMPOSE_PROJECT_NAME`` environment
+    variable.)
+
+    If you are not part of the ``docker`` group, then you need to run every
+    docker command with ``sudo``.
+
+To build the image:
+
+.. sourcecode:: bash
+
+    docker compose -p cms -f docker-compose.test.yml build testcms
+
+To run the tests:
 
 .. sourcecode:: bash
 
-    sudo docker-compose -f docker-compose.test.yml build cms_test
+    docker compose -p cms -f docker-compose.test.yml run --rm testcms
 
-Then you can run the tests:
+Another option is to add the ``--build`` flag to the ``run`` command, to perform
+a new build before running the tests:
 
 .. sourcecode:: bash
 
-    sudo docker-compose -f docker-compose.test.yml run --rm cms_test
+    docker compose -p cms -f docker-compose.test.yml run --build --rm testcms
 
-This command will create a ``cms_test_db`` container for the database which
-**will not** be automatically deleted, and a ``cms_test`` container for CMS
-which will be automatically deleted (because of the ``--rm`` flag) upon exiting.
+This command will create (assuming you used ``-p cms``) a ``cms-testdb-1``
+container for the database which **will not** be automatically deleted, and a
+``cms-testcms-run-<random_string>`` container for CMS which will be
+automatically deleted (because of the ``--rm`` flag) upon exiting.
 
-To delete the ``cms_test_db`` container after testing you can run:
+To delete the ``cms-testdb-1`` container after testing you can run:
 
 .. sourcecode:: bash
 
-    sudo docker rm -f cms_test_db
+    docker rm -f cms-testdb-1