Docker Compose v2 compatibility (#9759)

* Document Docker Compose v2 compatibility * Move the warning about Docker Compose v2 to troubleshooting, write something on troubleshooting the network * Rephrase warning text slightly * Update .env Co-authored-by: Manuel Kaufmann <[email protected]> * Add some semantic linebreaks * Remove the /etc/hosts troubleshooting step, it's not actual troubleshooting * Remove troubleshooting of network failures Co-authored-by: Manuel Kaufmann <[email protected]>
readthedocs · Nov 29, 2022 · e304011 · e304011
1 parent 4ffac70
commit e304011
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 2 deletions.
diff --git a/.env b/.env
@@ -1 +1,5 @@
 COMPOSE_PROJECT_NAME=community
+# Current setup assumes Docker Compose v1.
+# In v2, underscores are replaced by dashes in image and network names,
+# which breaks the assumption.
+COMPOSE_COMPATIBILITY=true
diff --git a/docs/dev/install.rst b/docs/dev/install.rst
@@ -4,8 +4,8 @@ Development Installation
 .. meta::
    :description lang=en: Install a local development instance of Read the Docs with our step by step guide.
 
-These are development setup and :ref:`standards <install:Core team standards>` that are followed to by the core development team. If you are a contributor to Read the Docs,
-it might a be a good idea to follow these guidelines as well.
+These are development setup and :ref:`standards <install:Core team standards>` that are followed to by the core development team.
+If you are a contributor to Read the Docs, it might a be a good idea to follow these guidelines as well.
 
 Requirements
 ------------
@@ -224,6 +224,17 @@ For others, the webhook will simply fail to connect when there are new commits t
 Troubleshooting
 ---------------
 
+.. warning::
+
+    The environment is developed and mainly tested on Docker Compose v1.x.
+    If you are running Docker Compose 2.x, please make sure you have ``COMPOSE_COMPATIBILITY=true`` set.
+    This is automatically loaded via the ``.env`` file.
+    If you want to ensure that the file is loaded, run:
+
+    .. code-block:: console
+
+        source .env
+
 Builds fail with a generic error
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -267,6 +278,7 @@ you have to follow these steps:
 
 Once this is done, you should be able to trigger a new build on that project and it should succeed.
 
+
 Core team standards
 -------------------