From 3896952508a17aeb0e157dec682b25da73d33736 Mon Sep 17 00:00:00 2001
From: William Di Luigi <williamdiluigi@gmail.com>
Date: Sat, 13 May 2023 12:36:44 +0200
Subject: [PATCH] Improve documentation on how to run tests

Also update gitignore / dockerignore
---
 .dockerignore         |  1 +
 .gitignore            |  1 +
 codecov/.gitkeep      |  0
 docs/Docker image.rst | 34 ++++++++++++++++++++++++++++++++++
 docs/index.rst        |  1 +
 5 files changed, 37 insertions(+)
 create mode 100644 codecov/.gitkeep
 create mode 100644 docs/Docker image.rst

diff --git a/.dockerignore b/.dockerignore
index ecbeca19d9..50d39eda50 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -2,3 +2,4 @@
 Dockerfile
 docker-compose*.yml
 .vagrant/
+codecov/
diff --git a/.gitignore b/.gitignore
index 5b1d9142ca..81939ad6c0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,3 +13,4 @@ cache/
 lib/
 log/
 .vagrant/
+codecov/
diff --git a/codecov/.gitkeep b/codecov/.gitkeep
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/docs/Docker image.rst b/docs/Docker image.rst
new file mode 100644
index 0000000000..74e54a1ae6
--- /dev/null
+++ b/docs/Docker image.rst	
@@ -0,0 +1,34 @@
+Docker image
+************
+
+We provide a docker image (defined in :gh_blob:`Dockerfile`) that can be used to
+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.
+
+.. _docker-image_running-tests:
+
+Running tests
+=============
+
+First you need to build the image:
+
+.. sourcecode:: bash
+
+    sudo docker-compose -f docker-compose.test.yml build cms_test
+
+Then you can run the tests:
+
+.. sourcecode:: bash
+
+    sudo docker-compose -f docker-compose.test.yml run --rm cms_test
+
+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.
+
+To delete the ``cms_test_db`` container after testing you can run:
+
+.. sourcecode:: bash
+
+    sudo docker rm -f cms_test_db
diff --git a/docs/index.rst b/docs/index.rst
index fdfa658860..f12ed175f4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,6 +5,7 @@ Welcome to CMS's documentation!
    :maxdepth: 2
 
    Introduction
+   Docker image
    Installation
    Running CMS
    Data model