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 on the most current development version

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 Quickstart section. If you need specific software versions or a specific branch, continue reading below.

Testing on an unmerged branch

  1. Install Docker for your system.

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

  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:

git clone https://github.com/tripal/tripal tripal-9999
cd tripal-9999

  1. 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:

git checkout 4.x
git branch tv4g1-issue1414-some_new_field
git checkout -b tv4g1-issue1414-some_new_field

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

../_images/docker.for.testing.branch.png 
git checkout -b tv4g1-issue1449-chadostorage-linkertables

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:

git fetch origin pull/1535/head:tv4g2-issue1534-chadoCvtermAutocompleteUpdate

  1. 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 build --tag=tripaldocker:testing-9999 --build-arg drupalversion="10.2.x-dev" --build-arg postgresqlversion="15" --file tripaldocker/Dockerfile-php8.3 ./

  1. 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:

sudo docker run --publish=8080:80 -tid --name=testing-9999 --volume=$(pwd):/var/www/drupal9/web/modules/contrib/tripal tripaldocker:testing-9999

  1. And finally we need to start up our PostgreSQL database inside the docker container.

sudo docker exec testing-9999 service postgresql restart

  1. 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 the install Tripal using Docker usage section.

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

sudo docker exec -it testing-9999 /bin/bash

  1. If at some point you reboot your test system, you can restart this docker container with:

sudo docker start testing-9999
sudo docker exec testing-9999 service postgresql restart

  1. Listing existing containers, include -a to show containers that are not running.

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

  1. Listing existing images.

sudo docker images
REPOSITORY                   TAG            IMAGE ID       CREATED          SIZE
tripaldocker                 testing-9999   6b09ee09dd54   29 minutes ago   1.61GB

  1. Cleanup. Stopping the docker container.

sudo docker stop testing-9999

  1. Deleting the docker container and image when you are done with it.

sudo docker rm testing-9999
sudo docker rmi tripaldocker:testing-9999