Skip to content

Commit

Permalink
Merge pull request #63 from tripal/updates-for-tripal-pr1821
Browse files Browse the repository at this point in the history 
Update docs for tripal PR #1821
  • Loading branch information
@laceysanderson
laceysanderson committed Mar 26, 2024
2 parents 7317d2c + 3b3479c commit a0e9bbf
Show file tree
Hide file tree
Showing 3 changed files with 89 additions and 149 deletions.
111 changes: 70 additions & 41 deletions docs/contributing/docker-for-testing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,86 +3,115 @@ Creating a Docker for Testing

This section describes the procedure to create and run a docker container from a specific branch from the Tripal repository. This is helpful for testing your own proposed changes, or testing another contributor's proposed changes, since the full install process will be performed on the branch.

Testing an unmerged pull request
--------------------------------
Testing on the most current development version
-----------------------------------------------

1. An unmerged pull request will be associated with a particular branch. You will see the branch name on the GitHub page for that pull request. Use this branch name in the following procedure. For example, it may appear as
If you just want to test functionality of the current development version of Tripal, you can build a docker container as described in the Docker :ref:`Quickstart` section. If you need specific software versions or a specific branch, continue reading below.

.. image:: docker.for.testing.branch.png

Testing on an unmerged branch
-----------------------------

1. `Install Docker <https://docs.docker.com/get-docker>`_ for your system.

2. Change to a suitable working directory on your local test system.

3. The original issue number is part of the branch name, for clarity we will use it in the docker name. In the following examples we will use 9999, but use the appropriate issue number.
3. Clone the most recent version of Tripal 4, keeping track of where you cloned it. To keep things organized, you may want to include the issue number, in these examples it is ``9999``:

.. code-block:: bash
git clone https://github.com/tripal/tripal tripal-9999
cd tripal-9999
4. If you want to contribute to core, you always want to make a new branch, do not work directly on the ``4.x`` branch. Use following naming convention for branches: ``tv4g[0-9]-issue\d+-[optional short descriptor]``.

- ``tv4g[0-9]`` indicates the functionality group the branch relates to. See tags for groups available.
- ``issue\d+`` indicates the issue describing the purpose of the branch. By making a new issue for each major task before we start working on it, we give room for others to jump in and save you time if something is already done, beyond scope, or can be made easier by something they are working on!
- ``[optional short descriptor]`` can be anything without spaces. This is meant to make the branches more readable so we don’t have to look up the issue every time. You are encouraged to only have one branch per issue! That said, there are some edge-cases where multiple branches may be needed (i.e. partitioned reviews) where variations in the optional short description can make the purpose of multiple branches clear.

Example for creating a new branch for creating a new field. Base your new branch on the main ``4.x`` branch:

.. code::
.. code-block:: bash
git clone https://github.com/tripal/tripal tripal-9999
cd tripal-9999
git checkout 4.x
git branch tv4g1-issue1414-some_new_field
git checkout -b tv4g1-issue1414-some_new_field
4. Now checkout the branch you want to test
Or if you want to test an unmerged pull request, it will be associated with a particular branch. You will see the branch name on the GitHub page for that pull request. Use this branch name in the following procedure. For example, it may appear as

.. code::
.. image:: docker.for.testing.branch.png

git checkout tv4g4-issue9999-example-branch
.. code-block:: bash
5. We will create the docker image, this takes a bit of time to complete.
git checkout -b tv4g1-issue1449-chadostorage-linkertables
.. code::
If the contributor's branch is in their own repository, checking it out will be slightly different, you will need to include the pull request number. For example, for pull request #1535:

sudo docker build --tag=tripaldocker:testing-9999 --build-arg drupalversion="10.1.x-dev" --file tripaldocker/Dockerfile-php8.1-pgsql13 ./
.. code-block:: bash
6. We will now create a running docker container from this image, and map the web port to a value available on the test system.
git fetch origin pull/1535/head:tv4g2-issue1534-chadoCvtermAutocompleteUpdate
.. code::
5. We will now build the docker **image**, this takes a bit of time to complete. You may want to specify a particular Drupal version, PHP version, or PostgreSQL version. The PHP version is part of the docker file name, the other versions are specified through the ``--build-arg`` parameters. For example:

sudo docker run --publish=80:80 -tid --name=testing-9999 --volume=$(pwd):/var/www/drupal9/web/modules/contrib/tripal tripaldocker:testing-9999
.. code::
If you wanted to use a different port on the host system, for example 8080, just modify the publish part of the command:
sudo docker build --tag=tripaldocker:testing-9999 --build-arg drupalversion="10.2.x-dev" --build-arg postgresqlversion="15" --file tripaldocker/Dockerfile-php8.3 ./
.. code::
6. We will now create a running docker **container** using the **image** we just built. We will map the web port `80` to a value available on the local test system. For example, we will select port ``8080``:

--publish=8080:80
.. code::
7. And finally we need to start up Postgres inside the docker container.
sudo docker run --publish=8080:80 -tid --name=testing-9999 --volume=$(pwd):/var/www/drupal9/web/modules/contrib/tripal tripaldocker:testing-9999
.. code::
7. And finally we need to start up our PostgreSQL database inside the docker container.

sudo docker exec testing-9999 service postgresql restart
.. code::
8. The Tripal site should now be available to evaluate at http://localhost:80
sudo docker exec testing-9999 service postgresql restart
8. The Tripal site should now be available to evaluate at http://localhost:8080 or whatever other port number you selected.

For more details about TripalDocker including the site administrator login information and more usage commands see :ref:`the install Tripal using Docker usage section<Development Site Information:>`.

9. If you need a shell inside the docker, such as to run a drush command, use

.. code::
.. code::
sudo docker exec -it testing-9999 /bin/bash
sudo docker exec -it testing-9999 /bin/bash
10. If at some point you reboot your test system, you can restart this docker container with:

.. code::
.. code::
sudo docker start testing-9999
sudo docker exec testing-9999 service postgresql restart
sudo docker start testing-9999
sudo docker exec testing-9999 service postgresql restart
11. Listing existing containers, include ``-a`` to show containers that are not running.

11. Listing existing images
.. code::
.. code::
sudo docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
9e29c051c2ed tripalproject/tripaldocker:latest "init.sh" 2 hours ago Up 2 hours 5432/tcp, 9003/tcp, 0.0.0.0:8080->80/tcp, :::8080->80/tcp t4
2f7575fe3940 tripaldocker:testing-9999 "init.sh" 3 days ago Exited (137) 2 days ago 9999
sudo docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
tripaldocker testing-9999 6b09ee09dd54 29 minutes ago 1.61GB
11. Listing existing images.

.. code::
sudo docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
tripaldocker testing-9999 6b09ee09dd54 29 minutes ago 1.61GB
12. Cleanup. Stopping the docker container.

.. code::
.. code::
sudo docker stop testing-9999
sudo docker stop testing-9999
13. Deleting the docker container and image when you are done with it.

.. code::
sudo docker rm testing-9999
sudo docker rmi tripaldocker:testing-9999
.. code::
For more details about TripalDocker including the site administrator login information and more usage commands see :ref:`the install Tripal using Docker usage section<Development Site Information:>`.
sudo docker rm testing-9999
sudo docker rmi tripaldocker:testing-9999
123 changes: 17 additions & 106 deletions docs/install/docker.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,18 @@ Software Stack

Currently we have the following installed:
- Debian Bullseye(11)
- PHP 8.2.12 with extensions needed for Drupal (Memory limit 1028M)
- PHP 8.2.17 with extensions needed for Drupal (Memory limit 1028M)
- Apache 2.4.56
- PostgreSQL 13.11 (Debian 13.11-0+deb11u1)
- Composer 2.6.5
- Drush 12.4.2
- Drupal 10.1.x-dev downloaded using composer (or as specified by drupalversion argument).
- PostgreSQL 16.2 (Debian 16.2-1.pgdg110+2)
- Composer 2.7.2
- Drush 12.5.1.0
- Drupal 10.2.5-dev downloaded using composer (or as specified by drupalversion argument).
- Xdebug 3.2.1

Quickstart
----------

1. Run the image in the background mapping it's web server to your port 9000.
1. Run the image in the background mapping its web server to your port 9000.

a) Stand-alone container for testing or demonstration.

Expand Down Expand Up @@ -65,7 +65,7 @@ Usage

.. code::
docker exec -it t4 psql --user docker sitedb
docker exec -it t4 psql --user docker sitedb
- Run Drush to generate code for your module!

Expand All @@ -79,6 +79,15 @@ Usage
docker exec t4 drush cr
- Get version information:

.. code::
docker exec t4 drush status
docker exec t4 php -v
docker exec t4 psql --version
docker exec t4 apache2 -v
- Run Composer to upgrade Drupal

.. code::
Expand All @@ -88,105 +97,7 @@ Usage
Detailed Setup for Core Development
------------------------------------

Using Latest tagged version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. `Install Docker <https://docs.docker.com/get-docker>`_ for your system.

2. Clone the most recent version of Tripal 4 keeping track of where you cloned it.

.. code-block:: bash
mkdir ~/Dockers
cd ~/Dockers
git clone https://github.com/tripal/tripal
cd tripal
git checkout 4.x
3. When editing core always make a new branch. Use following naming convention for branches: ``tv4g[0-9]-issue\d+-[optional short descriptor]``.

- ``tv4g[0-9]`` indicates the functionality group the branch relates to. See tags for groups available.
- ``issue\d+`` indicates the issue describing the purpose of the branch. By making a new issue for each major task before we start working on it, we give room for others to jump in and save you time if something is already done, beyond scope, or can be made easier by something they are working on!
- ``[optional short descriptor]`` can be anything without spaces. This is meant to make the branches more readable so we don’t have to look up the issue every time. You are encouraged to only have one branch per issue! That said, there are some edge-cases where multiple branches may be needed (i.e. partitioned reviews) where variations in the optional short description can make the purpose of multiple branches clear.

Example for new branch for creating a new field:

.. code-block:: bash
git checkout -b tv4g1-issue1414-data__sequence_length
4. Create a docker container based on the most recent TripalDocker image with your cloned version of Tripal4 mounted inside it.

.. code-block:: bash
cd t4
docker run --publish=9000:80 --name=t4 -tid --volume=$(pwd):/var/www/drupal/web/modules/contrib/tripal tripalproject/tripaldocker:latest
The first time you run this command you will see ``Unable to find image 'tripalproject/tripaldocker:latest' locally``. This is not an error! It's just a warning and the command will automatically pull the image from the docker cloud.

So, what does this command mean? I'll try to explain the parts below for users new to docker. If you are familiar with docker, feel free to ignore the next points!

- The ``docker run`` command creates a container from a docker image. You can think of a dockerfile as instructions, an image as an OS and a container as a running machine.
- The ``--name=t4`` is how you will access the container later using ``docker exec`` commands as shown in the usage section.
- The ``-tid`` part runs the container in the background with an interactive terminal ready to be accessed using exec.
- The ``--publish=9000:80`` opens port 9000 on your computer and ensures when you access localhost:9000 you will see the website inside the container.
- The ``--volume=[localpath]:[containerpath]`` ensures that your local changes will be sync'd with that directory inside the container. This makes development in the container a lot easier!

The command above was written for linux or mac users. Here is some information for Windows users.
- For Windows users the above command will not work as written. Specifically, the ``$(pwd)`` needs to be replaced with the absolute path in including the t4 directory.

.. code-block:: bash
docker run --publish=9000:80 --name=t4 -tid --volume=C:\Users\yourusername\Dockers\t4:/var/www/drupal/web/modules/contrib/tripal tripalproject/tripaldocker:latest``
5. Start the PostgreSQL database.

.. code-block:: bash
docker exec t4 service postgresql start
**This will create a persistent Drupal/Tripal site for you to play with! Data is stored even when your computer restarts and Tripal will already be enabled with Chado installed.**

**Furthermore, the --volume part of the run command ensures any changes made in your local directory are automatically copied into the docker container so you can live edit your website.**

Testing install for a specific branch or update the docker image.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following instructions will show you how to create the TripalDocker image from the code existing locally. **This should only be needed if you have made changes to Tripal 4 that impact the installation process, you have created a new module and/or if you have created a new Tripal release. Otherwise, you should be able to use the image from docker hub accessed via the docker pull command.**

First if you do not have a local copy of the t4 repository, you can use the following instructions to get one. If you do have a copy already, make sure it is up to date and contains the changes you would like to test.

.. code-block:: bash
mkdir ~/Dockers
cd ~/Dockers
git clone https://github.com/tripal/tripal
git checkout 4.x
Next, you use the `docker build <https://docs.docker.com/engine/reference/commandline/build/>`_ command to create an image from the existing TripalDocker Dockerfile. Since we are testing Tripal 4 on multiple versions of Drupal, you can set the Drupal major version using the drupalversion argument as shown below. The version of Drupal used for the latest tag is the default value of the argument in the Dockerfile.

.. code-block:: bash
cd t4
docker build --tag=tripalproject/tripaldocker:drupal10.1.x-dev --build-arg drupalversion='10.1.x-dev' ./
This process will take a fair amount of time as it completely installs Drupal, Tripal and PostgreSQL. You will see a large amount of red text but hopefully not any errors. You should always test the image by running it before pushing it up to docker hub!

.. note::

Make sure the drupal version specified in the tag matches the build argument. The value of ``drupalversion`` must match one of the available tags on `Packagist drupal/core <https://packagist.org/packages/drupal/core>`_.

.. warning::

If your new changes to Tripal 4 break install, you will experience one of the following depending on the type of error:

1. The build command executed above will not complete without errors.
2. When you run the image after it is built including starting PostgreSQL, you will not have a functional Tripal site.

.. note::

To **test your image**, execute any of the ``docker run`` commands documented above making sure to also start PostgreSQL (i.e. ``docker exec t4 service postgresql restart``). At this point you will already have Drupal, Tripal and Chado installed. It is recommended to also do a quick test of core functionality which may have been impacted by any recent changes.
If you want to contribute to Tripal development, you will likely want to create a branch to work on and create a Docker using this branch, or on another contributor's branch. For instructions on how to do this, see the section :ref:`Creating a docker for testing`

Troubleshooting
---------------
Expand Down
4 changes: 2 additions & 2 deletions docs/install/requirements.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ Requirements

- Drupal (see supported versions below)
- Drupal core modules: Search, Path, Views, and Field.
- PostgreSQL 10+
- PHP 8 (tested with 8.0 + 8.1)
- PostgreSQL 12+
- PHP 8 (tested with 8.1, 8.2, 8.3)
- Apache 2+
- Composer 2+
- UNIX/Linux
Expand Down

0 comments on commit a0e9bbf

Please sign in to comment.