From 5d89e68ba3d0e66f87bc6dad5c7951887246bc3c Mon Sep 17 00:00:00 2001
From: Lukas Holecek <hluk@email.cz>
Date: May 17 2021 09:19:49 +0000
Subject: docs: Update docker-compose developer documentation


---

diff --git a/docs/docker-compose.rst b/docs/docker-compose.rst
index 37e861b..2572962 100644
--- a/docs/docker-compose.rst
+++ b/docs/docker-compose.rst
@@ -1,65 +1,90 @@
 Docker-compose for Greenwave
-===========================================
+============================
 
-Quickstart
-----------
+To run functional tests or verify interoperability with ResultsDB and WaiverDB
+services, you can use ``podman-compose`` (or ``docker-compose``) to run the
+services in a containerized environment.
 
-**Quick Tip:** Use `make` to run frequent commands mentioned below.
+Install ``podman-compose`` either using ``pip`` or from a package:
 
-Start local development containers of ResultsDB and WaiverDB using
-``docker-compose``. If you want the containers to run in the foreground, omit
-the ``-d`` flag. If you want to create the containers again (after some code
-changes) add ``--force-recreate`` flag.
+.. code-block:: console
+
+  sudo dnf install podman-compose
+
+Makefile and ``make`` commands are used here to simplify setting up the
+development containers.
+
+Clone dependencies first (these should be in the same parent directory as
+Greenwave):
 
 .. code-block:: console
 
-  $ docker-compose up -d
+  git clone https://pagure.io/waiverdb.git ../waiverdb/
+  git clone https://pagure.io/taskotron/resultsdb.git ../resultsdb/
 
-Install development requirements:
+Build container images:
 
 .. code-block:: console
 
-  $ docker-compose exec dev pip3 install --user -r dev-requirements.txt
+  make build
 
-You can run the unit and functional tests with the following command:
+Start the containers:
 
 .. code-block:: console
 
-  $ docker-compose exec dev pytest
+  make up
 
-You could encounter following error when executing the application or tests in
-both in and outside the container.
+Verify that containers are running:
 
 .. code-block:: console
 
-  ImportError while loading conftest '/code/conftest.py'.
-  py._path.local.LocalPath.ImportMismatchError: ('conftest', '/home/user/proj/greenwave/conftest.py', local('/code/conftest.py'))
+  podman ps
+
+Check logs if needed:
+
+.. code-block:: console
+
+  podman logs greenwave_dev_1
+
+Run tests and code linters:
+
+.. code-block:: console
+
+  make test
+
+Run a specific test:
+
+.. code-block:: console
+
+  make pytest ARGS="-vv -x greenwave/tests/test_rules.py -k test_remote_rule
 
-To resolve this, run this command in the project directory:
+Stop the containers:
 
 .. code-block:: console
 
-  $ find -name '*.pyc' -delete
+  make down
 
-To execute tests for WaiverDB you also need to install the development
-dependencies first.
+The Greenwave container is restarted automatically if the code changes.
+Sometimes this can fail due to syntax errors or bugs in the code. In such case
+restart the container with:
 
 .. code-block:: console
 
-  $ docker-compose exec waiverdb pip3 install --user -r requirements.txt
-  $ docker-compose exec waiverdb dnf -y install python3-ldap
-  $ docker-compose exec waiverdb python3 -m pytest
+  podman restart greenwave_dev_1
 
-Quick How To
-------------
+You could encounter the following error when executing the application or
+tests:
 
-Installation
-~~~~~~~~~~~~
+.. code-block:: console
+
+  ImportError while loading conftest '/code/conftest.py'.
+  py._path.local.LocalPath.ImportMismatchError: ('conftest', '/home/user/proj/greenwave/conftest.py', local('/code/conftest.py'))
+
+To resolve this, remove old generated ``*.pyc`` files in the project directory:
 
-To run docker-compose you need to be able to run the regular docker
-command line.  Once you have that working you can install compose with:
+.. code-block:: console
 
-``{yum|dnf|brew} install docker-compose``
+  find -name '*.pyc' -delete
 
 See the `docker-compose reference`_ for a full description.