Merge pull request #3159 from chaoss/docker-docs

Update documentation to new docker compose

Author: sgoggins

README.md

@@ -118,6 +118,9 @@ Contributors
 - `Georg J.P. Link <https://github.com/GeorgLink/>`_
 - `Gary P White <https://github.com/garypwhite/>`_
 
+GSoC 2025 Participants
+-----------------------
+
 GSoC 2022 participants
 -----------------------
 - `Kaxada <https://github.com/kaxada>`_

docs/source/docker/docker.rst

@@ -1,4 +1,4 @@
-Docker
+Docker Image Breakdown
 =================
 
 Augur provides a separate Docker image for each layer of our application (database, backend, and frontend). This section details how to build and run these images locally for testing, and also describes how to set up our test environment using Docker.

docs/source/docker/getting-started.rst

@@ -20,9 +20,47 @@ The rest of this section of the documentation assumes you have a working install
 
 If you are less familiar with Docker, or experience issues you cannot resolve attempting our "quick start", please follow the instructions in this section, and the next few pages, to set up your environment.
 
+Docker Compose
+------------
+
+For quickest start up, set up Docker or Podman desktop with a machine with roughly
+the following resources (or more):
+
+- 8 CPUs 
+- 100 GB disk
+- 10 GB RAM
+
+Clone the Augur repository and create a .env file in the top level directory 
+with the following fields: 
+
+.. code:: python
+
+    AUGUR_DB=augur
+    AUGUR_DB_USER=augur
+    AUGUR_DB_PASSWORD=password_here
+
+    AUGUR_GITHUB_API_KEY=ghp_value_here
+    AUGUR_GITHUB_USERNAME=gh_username
+    AUGUR_GITLAB_API_KEY=placeholder
+    AUGUR_GITLAB_USERNAME=placeholder
+
+Then run:
+
+.. code:: shell 
+
+    docker compose up --build 
+
+or 
+
+.. code:: shell 
+    
+    podman compose up --build 
+
+And augur should be up and running! 
+
 Credentials
 ------------
-Before you get started with Docker, you'll need to set up a PostgreSQL instance either locally or using a remote host. Alternatively, you can also set up the database within a docker container either manually or through docker compose.
+If you want to create a DB outside of using Docker/Podman Compose, you'll need to set up a PostgreSQL instance either locally or using a remote host. 
 
 .. note::
 
@@ -39,7 +77,7 @@ If you don't care if your data doesn't get persisted or are doing local developm
 
 .. warning::
 
-    Using a Docker container as a production database is `not recommended <https://vsupalov.com/database-in-docker/>`_. You have been warned!
+    There are conflicting opinions on using Docker for a production database. 
 
 If you're more interested in doing local development, we recommend using our Docker testing environment image - more on that later.
 

docs/source/docker/quick-start.rst

@@ -9,13 +9,36 @@ Before you get off to such a quick start, go ahead and
   
      git checkout dev 
   
-  4. Usually, we'll have you checkout the `dev` branch.
-  5. Make sure to install all the pre-requisites here: https://oss-augur.readthedocs.io/en/main/getting-started/installation.html#dependencies
+  4. Create a .env file in the top level directory with the following fields: 
 
+.. code:: python
+
+    AUGUR_DB=augur
+    AUGUR_DB_USER=augur
+    AUGUR_DB_PASSWORD=password_here
+
+    AUGUR_GITHUB_API_KEY=ghp_value_here
+    AUGUR_GITHUB_USERNAME=gh_username
+    AUGUR_GITLAB_API_KEY=placeholder
+    AUGUR_GITLAB_USERNAME=placeholder
+
+5. Build the container using one of the following commands:
+
+.. code:: shell 
+
+    docker compose up --build 
+
+or 
+
+.. code:: shell 
+
+    podman compose up --build 
+
+And augur should be up and running! 
 
 .. note::
 
-  **Quick Start**: 
+  **Running against an external database**: 
 
   If you want to start running docker against an external database right away: 
 
@@ -34,11 +57,14 @@ Before you get off to such a quick start, go ahead and
 
   .. code-block:: 
 
-    AUGUR_GITHUB_API_KEY=xxxxxxxxxxxxxxxxxxxxxxx 
-    AUGUR_GITHUB_USERNAME=usernameGithub
-    AUGUR_GITLAB_API_KEY=xxxxxxxxxxxxxxxxxxxxxxx
-    AUGUR_GITLAB_USERNAME=usernameGitlab
-    AUGUR_DB=yourDBString
+    AUGUR_DB=augur
+    AUGUR_DB_USER=augur
+    AUGUR_DB_PASSWORD=password_here
+
+    AUGUR_GITHUB_API_KEY=ghp_value_here
+    AUGUR_GITHUB_USERNAME=gh_username
+    AUGUR_GITLAB_API_KEY=placeholder
+    AUGUR_GITLAB_USERNAME=placeholder
 
   4. Execute the code from the base directory of the Augur repository:
 

docs/source/getting-started/dev-osx-install.rst

@@ -598,23 +598,3 @@ You can stop augur with ``augur backend stop``, followed by
 so Augur can shutdown more gently. There is no issue with data integrity
 if you issue them seconds apart, its just that stopping is nicer than
 killing.
-
-Docker
-~~~~~~
-
-1. Make sure docker, and docker compose are both installed
-2. Modify the ``environment.txt`` file in the root of the repository to
-   include your GitHub and GitLab API keys.
-3. If you are already running postgresql on your server you have two
-   choices:
-
-   -  Change the port mappings in the ``docker-compose.yml`` file to
-      match ports for Postgresql not currently in use.
-   -  Change to variables in ``environment.txt`` to include the correct
-      values for your local, non-docker-container database.
-
-4. ``sudo docker build -t augur-new -f docker/backend/Dockerfile .``
-5. ``sudo docker compose --env-file ./environment.txt --file docker-compose.yml up``
-   to run the database in a Docker Container or
-   ``sudo docker compose --env-file ./environment.txt --file docker-compose.yml up``
-   to connect to an already running database.

docs/source/getting-started/using-docker.rst

@@ -0,0 +1,38 @@
+Docker Compose
+===========
+For quickest start up, set up Docker or Podman desktop with a machine with roughly
+the following resources (or more).
+
+- 8 CPUs 
+- 100 GB disk
+- 10 GB RAM
+
+1. Clone the Augur repository https://github.com/chaoss/augur
+
+
+2. Create a .env file in the top level directory with the following fields: 
+
+.. code:: python
+
+    AUGUR_DB=augur
+    AUGUR_DB_USER=augur
+    AUGUR_DB_PASSWORD=password_here
+
+    AUGUR_GITHUB_API_KEY=ghp_value_here
+    AUGUR_GITHUB_USERNAME=gh_username
+    AUGUR_GITLAB_API_KEY=placeholder
+    AUGUR_GITLAB_USERNAME=placeholder
+
+3. Build the container using one of the following commands:
+
+.. code:: shell 
+
+    docker compose up --build 
+
+or
+
+.. code:: shell 
+
+    podman compose up --build 
+
+And augur should be up and running! 

docs/source/quick-start.rst

@@ -8,6 +8,7 @@ Select installation instructions from those most closely related to the operatin
 
    getting-started/new-install
    getting-started/dev-osx-install
+   getting-started/using-docker
 
 
 Explanations of Technologies
@@ -154,24 +155,4 @@ so Augur can shutdown more gently. There is no issue with data integrity
 if you issue them seconds apart, its just that stopping is nicer than
 killing.
 
-Docker
-~~~~~~
-
-1. Make sure docker, and docker compose are both installed
-2. Modify the ``environment.txt`` file in the root of the repository to
-   include your GitHub and GitLab API keys.
-3. If you are already running postgresql on your server you have two
-   choices:
-
-   -  Change the port mappings in the ``docker-compose.yml`` file to
-      match ports for Postgresql not currently in use.
-   -  Change to variables in ``environment.txt`` to include the correct
-      values for your local, non-docker-container database.
-
-4. ``sudo docker build -t augur-new -f docker/backend/Dockerfile .``
-5. ``sudo docker compose --env-file ./environment.txt --file docker-compose.yml up``
-   to run the database in a Docker Container or
-   ``sudo docker compose --env-file ./environment.txt --file docker-compose.yml up``
-   to connect to an already running database.
-