From 42ae63a7f5ea6e5552b05a00a0193c61bfe131fe Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 22 Dec 2020 10:47:45 +0100 Subject: [PATCH 01/10] Install pip via apt --- precice/Dockerfile.Ubuntu1804.home | 10 ++++++++-- precice/Dockerfile.Ubuntu1804.package | 6 +++++- precice/Dockerfile.Ubuntu2004.home | 6 ++++-- precice/Dockerfile.Ubuntu2004.package | 1 + 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/precice/Dockerfile.Ubuntu1804.home b/precice/Dockerfile.Ubuntu1804.home index fe8332feb..b2a35d95d 100644 --- a/precice/Dockerfile.Ubuntu1804.home +++ b/precice/Dockerfile.Ubuntu1804.home @@ -14,6 +14,7 @@ RUN apt-get -qq update && apt-get -qq install \ git \ python3-numpy \ python3-dev \ + python3-pip \ petsc-dev \ wget \ bzip2 \ @@ -43,10 +44,15 @@ RUN wget -nv 'https://www.mcs.anl.gov/petsc/mirror/release-snapshots/petsc-3.12. make all test RUN chown -R precice:precice /petsc -# Rebuild image if force_rebuild after that command -ARG CACHEBUST USER precice + +# Upgrade pip to latest version +RUN pip3 install --user --upgrade pip + +# Rebuild image from here on if `force_rebuild` is enabled +ARG CACHEBUST + WORKDIR /home/precice # Setting some environment variables for installing preCICE ENV CPLUS_INCLUDE_PATH="$CPLUS_INCLUDE_PATH:/usr/include/eigen3" \ diff --git a/precice/Dockerfile.Ubuntu1804.package b/precice/Dockerfile.Ubuntu1804.package index 435b460a3..f85587f4a 100644 --- a/precice/Dockerfile.Ubuntu1804.package +++ b/precice/Dockerfile.Ubuntu1804.package @@ -11,10 +11,11 @@ RUN apt-get -qq update && apt-get -qq install \ libboost-all-dev \ libeigen3-dev \ libxml2-dev \ - petsc-dev \ git \ python3-numpy \ python3-dev \ + python3-pip \ + petsc-dev \ wget \ bzip2 \ cmake && \ @@ -45,6 +46,9 @@ RUN apt-get -qq update && apt-get -qq install \ # Rebuild image if force_rebuild after that command ARG CACHEBUST + # Upgrade pip to latest version + RUN pip3 install --user --upgrade pip + USER precice WORKDIR /home/precice # Setting some environment variables for installing preCICE diff --git a/precice/Dockerfile.Ubuntu2004.home b/precice/Dockerfile.Ubuntu2004.home index ebc2434cd..bb8dc4c9b 100644 --- a/precice/Dockerfile.Ubuntu2004.home +++ b/precice/Dockerfile.Ubuntu2004.home @@ -15,8 +15,10 @@ RUN apt-get -qq update && apt-get -qq install \ libeigen3-dev \ libxml2-dev \ git \ - python-numpy \ - python-dev \ + python3-numpy \ + python3-dev \ + python3-pip \ + petsc-dev \ wget \ bzip2 \ cmake && \ diff --git a/precice/Dockerfile.Ubuntu2004.package b/precice/Dockerfile.Ubuntu2004.package index c161549e1..b3cc1650a 100644 --- a/precice/Dockerfile.Ubuntu2004.package +++ b/precice/Dockerfile.Ubuntu2004.package @@ -18,6 +18,7 @@ RUN apt-get -qq update && apt-get -qq install \ git \ python3-dev \ python3-numpy \ + python3-pip \ petsc-dev \ wget \ bzip2 \ From bae2bdfe68d56b4f451ba6b5699199ade59a6278 Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 17 Nov 2020 08:25:59 +0100 Subject: [PATCH 02/10] Allow ccx-adapter to fail --- .travis.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 4379e3c07..985f9ea1f 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,6 +16,9 @@ jobs: - name: "[18.04] SU2 <-> Calculix [unstable][failure allowed]" - name: "[20.04 PETSc] SU2 <-> Calculix [unstable][failure allowed]" - name: "[18.04 PETSc] OpenFOAM <-> CalculiX [FSI][failure allowed]" + - name: "[18.04] CalculiX adapter[failure allowed]" + - name: "[18.04] CalculiX adapter [PETSc][failure allowed]" + - name: "[20.04] CalculiX adapter [PETSc][failure allowed]" include: @@ -128,21 +131,21 @@ jobs: - python push_adapter.py --dockerfile adapters/Dockerfile.codeaster-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push.py - - name: "[18.04] CalculiX adapter" + - name: "[18.04] CalculiX adapter[failure allowed]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push.py - - name: "[18.04] CalculiX adapter [PETSc]" + - name: "[18.04] CalculiX adapter [PETSc][failure allowed]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation home --petsc yes --docker-username $DOCKER_USERNAME - python push_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation home --petsc yes --docker-username $DOCKER_USERNAME - python push.py - - name: "[20.04] CalculiX adapter [PETSc]" + - name: "[20.04] CalculiX adapter [PETSc][failure allowed]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu2004 --precice-installation package --petsc yes --docker-username $DOCKER_USERNAME From 11ad1c9a7bf87ede1791159faa11c6bb5e3ae2e4 Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 22 Dec 2020 10:30:35 +0100 Subject: [PATCH 03/10] Allow ccx adapter build failure --- .travis.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.travis.yml b/.travis.yml index 985f9ea1f..058bc8dac 100644 --- a/.travis.yml +++ b/.travis.yml @@ -16,9 +16,9 @@ jobs: - name: "[18.04] SU2 <-> Calculix [unstable][failure allowed]" - name: "[20.04 PETSc] SU2 <-> Calculix [unstable][failure allowed]" - name: "[18.04 PETSc] OpenFOAM <-> CalculiX [FSI][failure allowed]" - - name: "[18.04] CalculiX adapter[failure allowed]" - - name: "[18.04] CalculiX adapter [PETSc][failure allowed]" - - name: "[20.04] CalculiX adapter [PETSc][failure allowed]" + - name: "[18.04] CalculiX adapter [failure allowed]" + - name: "[18.04] CalculiX adapter [PETSc] [failure allowed]" + - name: "[20.04] CalculiX adapter [PETSc] [failure allowed]" include: @@ -131,21 +131,21 @@ jobs: - python push_adapter.py --dockerfile adapters/Dockerfile.codeaster-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push.py - - name: "[18.04] CalculiX adapter[failure allowed]" + - name: "[18.04] CalculiX adapter [failure allowed]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push.py - - name: "[18.04] CalculiX adapter [PETSc][failure allowed]" + - name: "[18.04] CalculiX adapter [PETSc] [failure allowed]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation home --petsc yes --docker-username $DOCKER_USERNAME - python push_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation home --petsc yes --docker-username $DOCKER_USERNAME - python push.py - - name: "[20.04] CalculiX adapter [PETSc][failure allowed]" + - name: "[20.04] CalculiX adapter [PETSc] [failure allowed]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu2004 --precice-installation package --petsc yes --docker-username $DOCKER_USERNAME From 5a00ec5dcf9d079592a8bb0daf5df2001eeea1b3 Mon Sep 17 00:00:00 2001 From: Eder-K Date: Wed, 18 Nov 2020 15:24:15 +0100 Subject: [PATCH 04/10] Remove 10m sleep command --- tests/TestCompose_of-ccx/docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/TestCompose_of-ccx/docker-compose.yml b/tests/TestCompose_of-ccx/docker-compose.yml index 1d11291fb..a8f35ffbf 100644 --- a/tests/TestCompose_of-ccx/docker-compose.yml +++ b/tests/TestCompose_of-ccx/docker-compose.yml @@ -31,7 +31,7 @@ services: - outer_fluid_input:/home/precice/Data/Input/ - configs:/home/precice/openfoam-adapter/configs/ command: > - /bin/bash -c "sleep 10m && source /usr/lib/openfoam/openfoam2006/etc/bashrc && + /bin/bash -c "source /usr/lib/openfoam/openfoam2006/etc/bashrc && ln -sf configs/* . && buoyantSimpleFoam -case /home/precice/Data/Input && mkdir /home/precice/Data/Output/Outer-Fluid && From cefa527dd009301bfb4293ebf75f2b17c21e82c8 Mon Sep 17 00:00:00 2001 From: Konrad Eder <53946421+Eder-K@users.noreply.github.com> Date: Mon, 23 Nov 2020 00:58:46 +0100 Subject: [PATCH 05/10] Fix dockerimage target --- tests/TestCompose_of-ca/docker-compose.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/TestCompose_of-ca/docker-compose.yml b/tests/TestCompose_of-ca/docker-compose.yml index 6c096f13b..5d1816380 100644 --- a/tests/TestCompose_of-ca/docker-compose.yml +++ b/tests/TestCompose_of-ca/docker-compose.yml @@ -3,7 +3,7 @@ services: # OpenFOAM Adapter openfoam-adapter-fluid: - image: "${SYSTEST_REMOTE}openfoam-adapter-ubuntu1804.home-develop" + image: "${SYSTEST_REMOTE}openfoam-adapter${PRECICE_BASE}" networks: - precicecomm volumes: @@ -22,7 +22,7 @@ services: # Code_Aster Adapter codeaster-adapter-solid: - image: "${SYSTEST_REMOTE}codeaster-adapter-ubuntu1804.home-develop" + image: "${SYSTEST_REMOTE}codeaster-adapter${PRECICE_BASE}" networks: - precicecomm volumes: From 422961b9b32fd8b09ff83adea6be66ea5e0a17ad Mon Sep 17 00:00:00 2001 From: Konrad Eder <53946421+Eder-K@users.noreply.github.com> Date: Tue, 8 Dec 2020 22:29:32 +0100 Subject: [PATCH 06/10] Update documentation (#257) * Update documentation * Clean up introduction text * Overhaul documentation * Fix errors * Format main readme * Update header * Overhaul trigger_systemtests explanation * Overhaul documentation * Update development.md * Add links to useful docs * Format sections * Overhaul documentation * Update link list * Fix grammar --- docs/README.md | 38 +++++++++++++++--- docs/adapters-ci.md | 85 ++++++++++++++++++++++++--------------- docs/adding_tasks.md | 45 +++++++++++++++++++++ docs/adding_tests.md | 82 ------------------------------------- docs/architecture.md | 96 +++++++++++++++++++++++++++++++------------- docs/development.md | 59 ++++++++++++++++----------- 6 files changed, 234 insertions(+), 171 deletions(-) create mode 100644 docs/adding_tasks.md delete mode 100644 docs/adding_tests.md diff --git a/docs/README.md b/docs/README.md index 4ba195fec..343f510bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,35 @@ -# preCICE systemtests documentation +# preCICE Systemtests Documentation -This folder provides general documentation of the preCICE system testing architecture. +Here you will find general documentation for the preCICE systemtesting architecture. -- General overview of the testing architecture is provided in [`architecture.md`](./architecture.md). This is the file you should read first. -- Handling of CI for the individual adapters is described in [`adapters-ci.md`](./adapters-ci.md) -- Some tips and practices for the development are found in [`development.md`](./development.md) +## Why use precice/systemtests? + +This repository fulfills a variety of functions, which are handled by separate files/folders. +Roughly outlined, these functions are: + +- Chronologically checking the integrity of preCICE and all related adapters for a variety of solvers. This is done by building them from source using Docker images. After a successful build the respective image is then uploaded to DockerHub for public use. These finished images are also involved in later tests/builds. When building the docker image for an adapter, for instance, we begin by pulling a Dockerhub image that has preCICE already installed. + +- Providing a method to trigger a systemtests build from other preCICE repositories (specifically the preCICE adapters) in order to checking the integrity of the specific adapter. + +- Logging results and storing debug output by pushing it to the repository `precice_st_output`. (This is subject to be replaced with a fitting storage mechanism in the future). + + +The repository written in a combination of Dockerfiles, Python, and Bash. The code execution is done on the CI platform Travis, though this is subject to change in the future (possibly migrating to GitLabCI/GitHubCI). + +## Where to start? + +### Useful Documentation + +* [Docker](https://docs.docker.com/) +* [Docker-compose](https://docs.docker.com/compose/) +* [TravisCI main docs](https://docs.travis-ci.com/) +* [TravisCI API](https://developer.travis-ci.com/) +* [Bash scripting](https://tiswww.case.edu/php/chet/bash/bashref.html) (most bash docs/cheatsheets you can find by googling are pretty good, this is only one example) +* [AWK scripting](https://www.grymoire.com/Unix/Awk.html) (as with bash, this is only one example) + +### How to use systemtests + +- [`architecture.md`](./architecture.md): General overview of the testing architecture. **(If you are new, read this first!)** +- [`adapters-ci.md`](./adapters-ci.md): How to handle builds originating from adapter repositories. +- [`adding_tasks.md`](./adding_tasks.md): Explanation of the `.travis.yml` job structure. +- [`development.md`](./development.md): Tips and common practices for development. diff --git a/docs/adapters-ci.md b/docs/adapters-ci.md index b0b65225d..492e607a2 100644 --- a/docs/adapters-ci.md +++ b/docs/adapters-ci.md @@ -1,47 +1,68 @@ -# Continuous Integration on adapters repositories +# Continuous Integration on adapter repositories -This file documents solution that ensures continuous integration for adapters, including different branch -and pull requests without unnecessary code duplication. +This file documents the use of the `trigger_systemtests.py` script, which ensures continuous integration for adapters. This primarily means that adapter repositories can create build testing their current code (including different branches +and pull request versions) without unnecessary code duplication. In order to understand this section in depth, one should read through the `trigger_systemtests.py` script as well (though starting with this document is probably more helpful). -## Triggering the build from the adapter +## Triggering a TravisCI build from the adapter -In order not to duplicate tests on different adapters, and to reuse functionality provided here, we use the Travis API -to trigger selected tests present in this repository after commits to the adapters repositories. This is done by -generating custom JSON with specification of the job and sending it to the Travis that triggers the build on this repository(For the overview of build triggering and custom jobs -see [here](https://docs.travis-ci.com/user/triggering-builds/)). -Correspondingly, in order to send this request a simple Travis job needs to be present on adapters repository, so that it runs the main triggering script. -Once the tests are finished, their return status is queried/sent back (controlled by `--wait` argument) to the Travis job on the adapter repository. -In case `--wait` flag is on, Travis job on adapter's repository essentially performs a blocking call, that does not return until tests finish (two running jobs -will be then seen in Travis dashboard - one for systemtests and one for the adapter). Alternatively, non-blocking call is possible - in that case, in order to indicate -failure of the test, the script will trigger "failing job" on the adapters repository if the test fails. +In order not to duplicate and store systemtest code on each of the adapter repositories, we instead reuse the testing system provided here. This is done by employing the Travis API to trigger Travis builds of selected test subsets from this systemtests repository after performing a commit on an adapter repository. -You can learn more from `trigger_systemtests.py`, which handles all of described functionality. +For this purpose, we use the `trigger_systemtests.py` script to generate custom JSON with fitting job specifications and sending it to TravisCI. If executed correcty, this triggers a build to start on the systemtests page on TravisCI. For an overview of build triggering and custom jobs see [this page](https://docs.travis-ci.com/user/triggering-builds/). -Since we don't need to run a full set of tests, only the following stages are added when generating the JSON job configuration file: +To illustrate the process of triggering a build, let's look at the operations in chronological order using [this example from the fenics-adapter repository](https://travis-ci.org/github/precice/fenics-adapter/builds/741877203): + +1. Firstly, a [change is commited on the adapter repository](https://github.com/precice/fenics-adapter/commit/71c6941fdb96de69bab139b706d66db228075737). + +2. TravisCI picks up on this commit and [initiates a build on the adapter repository](https://travis-ci.org/github/precice/fenics-adapter/builds/741877203). Note that this requires two things: the adapter repository must be listed as active in the TravisCI precice dashboard and the repository [must contain a `.travis.yml` file for TravisCI to execute](https://github.com/precice/fenics-adapter/blob/71c6941fdb96de69bab139b706d66db228075737/.travis.yml). + +3. TravisCI [boots up a machine to execute the instructions in the adapters `.travis.yml` file](https://travis-ci.org/github/precice/fenics-adapter/builds/741877203). These contain a command to pull one file, `trigger_systemtests.py`, from the precice/systemtests repository and call it with a certain set of arguments that is specific to this adapter. Note that this step is performed on the TravisCI page of the adapter, not on systemtests! + +4. The TravisCI machine creates a JSON-formatted request to build a job on precice/systemtests and sends it to Travis. The request contains a simplified build job of two stages: - Building the adapter -- Running the tests in which it participates +- Running tests in which the adapter participates + + This request is then received and upon parsing creates a [second, independent build that runs on precice/systemtests](https://travis-ci.org/github/precice/systemtests/builds/741879219). After sending the request, the original adapter build will either exit immediately or stall until it hears back from the triggered systemtests build before stopping. This behavior is dictated [by the `--wait` flag, which if set will cause the build to wait until the systemtests one is resolved](https://github.com/precice/fenics-adapter/blob/71c6941fdb96de69bab139b706d66db228075737/.travis.yml#L10). + +5. Depending on the result of the triggered build, the original adapter build will either fail or succeed. -## Running on different branches and pull requests + *Note: that if we omit`--wait`, this build will immediately exit as 'success' before the actual build on systemtests resolves. In this case, the systemtests build will contain an additional command at its end that causes it to send back another build request to the original adapter repository. This third build only contains the command `return false` and thus serves as notification that the systemtests build corresponding to the commit has failed. (This is quite hacky and in practice never used, as we mostly use `--wait` in the adapters. If someone plans to build upon this feature, it is probably best to find a simpler way to achieve this callback.)* -During the adapter's Travis job, if it is identified that the job is running on a pull request on a non-master branch (using the -`TRAVIS_BRANCH` and `TRAVIS_PULL_REQUEST` environment variables), the generated JSON filed is patched with additional bash script that modifies -the adapter Dockerfiles with additional instruction to switch to the needed branch (the instruction should be injected prior -to actually building an image). +## Running on different branches/pull requests -The resulting image is then tagged with the name of the branch/pull request and pushed to [Dockerhub](https://hub.docker.com/u/precice). In the `docker-compose.yml` the image tag -is controlled using `{${SOLVER_NAME}_TAG}`( defaults to `latest`). Similarly, this environment variables is also specified in the specification of the Travis job -for every solver participating in the test. +During the adapters TravisCI job, the `trigger_systemtests.py` script checks if it is running on non-master-branch/pull-request-branch (using the `TRAVIS_BRANCH` and `TRAVIS_PULL_REQUEST` environment variables). If that is the case, the generated JSON file is patched with additional bash script calls that modify the adapters Dockerfile with additional instructions (such that it checks out the correct branch before cloning the repostory, for instance). + +The resulting adapter image is then tagged with the name of the branch/pull request and pushed to [DockerHub](https://hub.docker.com/u/precice). This is done to prevent the PR image from overwriting other images (e.g. the regularly used `develop` variant of the adapter). The test that follows after building the adapter will use this special image variant. More specifically, the tag is determined in `docker-compose.yml` with the `{${SOLVER_NAME}_TAG}` variable (defaults to `latest`). ## Adding CI for the adapter's repository -Add specifications of the adapter into the `adapter_info` dictionary in `trigger_systemtests`. -Then, the only thing remaining is to add a `.travis.yml` file to the adapter's repository, such as: +When setting up a new adapter to use the systemtests CI, the following modifications need to be made: + +- [The adapter repository must be activated on TravisCI](https://docs.travis-ci.com/user/tutorial/#to-get-started-with-travis-ci-using-github). + +- A `.travis.yml` file must be generated in the adapter repository. For illustration purposes let us consider [the fenics-adapter implementation of `.travis.yml`](https://github.com/precice/fenics-adapter/blob/71c6941fdb96de69bab139b706d66db228075737/.travis.yml) as an example: + + ```yaml + matrix: + include: + - os: linux + name: "Systemtests" + if: fork = false AND ( branch = master OR branch = develop ) + python: "3.6" + env: PY=python3 + script: + - curl -LO --retry 3 https://raw.githubusercontent.com/precice/systemtests/develop/trigger_systemtests.py + - travis_wait 60 $PY trigger_systemtests.py --adapter fenics --wait + ``` + + You don't have to match this exact format when creating your own `.travis.yml` file, but make sure that the following lines are included: + + 1. `if: fork = false AND ( branch = master OR branch = develop )`: this ensures that tests only run from the original repository (non-fork) and only if the commits are made to `master`/`develop` or a PR which targets these branches. + + 2. `- curl -LO --retry 3 https://raw.githubusercontent.com/precice/systemtests/develop/trigger_systemtests.py`: this pulls the latest `develop` version of `trigger_systemtests.py` for use in the adapter repository. + + 3. `- travis_wait 60 $PY trigger_systemtests.py --adapter fenics --wait` launches the request for the fenics-adapter with the `--wait` flag. Note that `travis_wait 60` is not necessary. - - if: branch = master - script: | - curl -LO --retry 3 https://raw.githubusercontent.com/precice/systemtests/master/trigger_systemtests.py - python3 trigger_systemtests.py --adapter openfoam +- A specification for the adapter must be added into the `adapter_info` dictionary in `trigger_systemtests`. -We also need to add a `TRAVIS_ACCESS_TOKEN` in each adapter's repository, as a secure variable to authenticate the build triggering. This token can be -found on the [Travis profile page](https://travis-ci.org/account/preferences). +- A `TRAVIS_ACCESS_TOKEN` for the TravisCI precice user must be added as [environment variable in the adapters repository](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings). This is required for the request to be permitted. You can find the token under the [Travis profile page](https://travis-ci.org/account/preferences). diff --git a/docs/adding_tasks.md b/docs/adding_tasks.md new file mode 100644 index 000000000..a53c62ee9 --- /dev/null +++ b/docs/adding_tasks.md @@ -0,0 +1,45 @@ +# How to add tasks + +To add a new tasks to the Travis build, simply add a corresponding entry in the `.travis.yml` file in a fitting stage under the `jobs: include:` section. The current stages are `Building preCICE`, `Building adapters`, `Tests`. + + +An entry should at least contain `name` and `script` keys such that the job can be run by Travis and identified in the build log. In this example the additional `if` conditions avoids this job to execute if the build is running on a fork of the systemtests repository. Many more specifications are available if necessary, check the [Travis docs](https://docs.travis-ci.com/) for more info. + +Most likely your preCICE build/adapter build/adapter test outputs some result data at the end, which in the case of precice- and adapter builds should be pushed to DockerHub using the respective `push_precice.py`/`push_adapter.py` scripts. On top of that, one can push a logfile recording the build status to the `precice_st_output` repository by calling `push.py`. If the performed job was a test, this `push.py` call can be augmented with the `-o` flag, which will also upload Output data to the repository (in addition to the logfile). Note that the `push.py` command makes use of information stored intermittently in `build_info.py`, which serves as a way to transmit information from scripts called earlier on in the command chain. This file is created by `push_precice.py`, `push_adapter.py` and `systemtesting.py` + + +Here is an example job we might run on TravisCI that builds the SU2 adapter: + +```bash + - stage: Building adapters + name: "[18.04] SU2 adapter" + if: fork = false + script: + - python build_adapter.py --dockerfile adapters/Dockerfile.su2-adapter --operating-system ubuntu1804 --precice-installation home --docker-username $DOCKER_USERNAME + - python push_adapter.py --dockerfile adapters/Dockerfile.su2-adapter --operating-system ubuntu1804 --precice-installation home --docker-username $DOCKER_USERNAME + - python push.py +``` +The three script commands perform the following actions: +- `build_adapter.py` builds the adapter image. In this case, it will build a SU2-adapter image using the respective Dockerfile under `adapters`, using a baseimage of preCICE that is named `precice/precice-ubuntu1804.home-develop`. More generally, this baseimage is called `{docker-username}/precice-{operating-system}.{precice-installation}-{branch}`, whereby `docker-username` will be set to `precice` when running in TravisCI (as this is the value given by `$DOCKER_USERNAME`). `branch` is an optional argument that was not explicitly specified in this call, therefore it defaults to `develop`. +- `push_adapter.py` will push the respective adapter image, using a similar naming convention: `{docker-username}/{adapter-name}-{operating-system}.{precice-installation}-{branch}`, which in this case resolves to `precice/su2-adapter-ubuntu1804.home-develop`. +- `push.py` will upload a log of the build to `precice_st_output`. + + +In the case of a test, the command looks a little different. Here an example where we test OpenFOAM-OpenFOAM: + +```bash + - stage: Tests + name: "[18.04] OpenFOAM <-> OpenFOAM" + script: + - python system_testing.py -s of-of -v + - python push.py +``` + +In the case of a test, we generally only use two script commands: +- `systemtesting.py` will execute the test we specify using `-s`, in this case `of-of` (the script will then execute the test files found under `tests/TestCompose_of-of`). The verbose `-v` flag is optional and will cause the script to print the full output of each participant to the console (useful when debugging tests). If this flag is omitted, the script will instead only give periodic updates about the current simulation status. +- `push.py` will upload a log of the test to `precice_st_output`, similar as with adapter/precice builds. Additionally, you can add the output flag `-o` to the script call to also have it push the generated `Output` folder containing all result files. This allows you to check the output produced on the CI platform, which otherwise is inaccessible and will be deleted at the end of the job. Note that keeping this flag enabled for a long time will cause `precice_st_output` to store a lot of (possibly unnecessary) data. + + +## Need help setting up a job? + +If you are experiencing any issues, don't hesitate to ask for assisstance on [Gitter](https://gitter.im/precice/Lobby) or [Discourse](https://precice.discourse.group/). diff --git a/docs/adding_tests.md b/docs/adding_tests.md deleted file mode 100644 index d49f86898..000000000 --- a/docs/adding_tests.md +++ /dev/null @@ -1,82 +0,0 @@ -# How to add tests - -To add a new test to the Travis build, simply add a corresponding entry in the `.travis.yml` file in a fitting stage under the `jobs: include:` section. The current stages are `Building preCICE`, `Building adapters`, `Tests`. - -Here is an example job which builds the SU2 adapter: - -```bash -- stage: Building adapters - name: SU2 adapter - if: fork = false - script: - - docker build -f adapters/Dockerfile.su2-adapter -t precice/su2-adapter-ubuntu1604.home-develop . -``` - -An entry should at least contain `name` and `script` keys such that the job can be run by travis and identified in the build log. In this example the additional `if` conditions avoids this job to execute if the build is running on a fork of the systemtests repository. Many more specifications are available if necessary, check the [Travis docs](https://docs.travis-ci.com/) for more info. - -## Post-script actions - -Most likely your preCICE build/adapter build/adapter test outputs some result data at the end, which should be either pushed to DockerHub (for docker images) of the 'precice_st_output' repository (for test logs). These pushes can be conditional as well, e.g. only pushing a docker image if the build actually exited successfully. -Such conditional pushes are realized by adding specific commands in `after_failure` and `deploy` sections. - -#### Post-failure - -Here is an example of how to use the `after_failure` key: -```bash - - stage: Tests - name: "[16.04] SU2 <-> Calculix" - script: - - python system_testing.py -s su2-ccx - after_failure: - - python push.py -t su2-ccx -``` -Youc can specify commands the same way you do for the main script. This code will only be run if the main script commands return a non-zero exit code. - -#### Post-success - -**Note**: `after_success` sections are available in TravisCI. However, it is strongly recommended to use `deploy`. The reason is that a build with failing code in `after_success` sections will still get shown as successful, which makes it harder to detect failures. - -A deployment requires several additional arguments to function properly. These do not need to be specifically adjusted for your test and can be directly copied into your test. Here is an code snippet from a deploying job: - -```bash - - stage: Building preCICE - name: "Arch Linux" - if: fork = false - script: - - docker build -f precice/Dockerfile.Arch -t precice/precice-arch-develop . - deploy: - skip_cleanup: true - provider: script - on: - all_branches: true - script: >- - echo "$DOCKER_PASSWORD" | docker login -u precice --password-stdin && - docker push precice/precice-arch-develop:latest -``` - -The `deploy: script` contains the actual commands you wish to execute after a successful run. Additionally, the following arguments must be provided inside the `deploy` key: - -- `skip_cleanup: true` - - This prevents TravisCI from stashing all changes made during the build, i.e. cleaning all results we actually wish to push. - - -- `provider: script` - - Specifies that the deployment phase uses our manually provided script. - - -- `on: all_branches: true` - - With this the deployment can be issued on any branch. This allows us to execute commands from the same branch that triggered a Travis build, and for any branch. If this key is not set, the deployment scripts would be run exclusively on `master` instead (independent of which branch the build runs on). - - -- `script: >- [actual deploy script]` - - The `>-` is *critical* here. For one, **deploy scripts can only consist of a single line**. This means that we have to chain commands together (note the `&&` at line end) and use `>` to extend them into multiple lines. The addition of the hyphen `-` prevents the last command to be trailed by a newline character `/n`. **If this hyphen is omitted, the `/n` character in the command might get parsed as only `n`, which appends a character to the final command and makes it invalid!** - - - -## Need help setting up a test? - -If you are experiencing any issues, don't hesitate to ask for assisstance on [Gitter](https://gitter.im/precice/Lobby) or [Discourse](https://precice.discourse.group/). diff --git a/docs/architecture.md b/docs/architecture.md index c9857444c..fc4e02639 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,66 +1,104 @@ # General architecture -When running on Travis tests are executed as specified in the file `.travis.yml` located in the root of the systemtests repository. The several stages of testing are outlined below. -If running a local tests (compared to the standard build on the Travis servers) the steps are identical, but the push to the remote DockerHub repository is absent. +## TravisCI -## Building preCICE +At the moment, the systemtest procedure is being run on the [TravisCI platform](https://travis-ci.org/github/precice). Note that this is subject to change soon: TravisCI itself is currently [migrating](https://docs.travis-ci.com/user/migrate/open-source-repository-migration) (changing the domain from `travis-ci.org` to `travis-ci.com`), and on top of that we plan on [transferring the systemtests to another platform alltogether](https://github.com/precice/systemtests/issues/253). + +Running tests on TravisCI has two requirements: the repository needs to be registered as active on TravisCI, and it must contain a file named `.travis.yml` located in the root of the repository. Assuming these criteria are met, TravisCI will then 'watch' the repository for changes and trigger a build whenever a change to the repository is made (the exact behavior of what to do is specified in the repository settings tab on the TravisCI dashboard). Once a build has been triggered, TravisCI boots up a virtual machine that executes commands as specified in `.travis.yml`. + +We structure TravisCI builds into three distinct stages; building preCICE, building adapters, and tests. Details of each stage are outlined below. + + +The python and bash scripts located in the systemtests root directory each serve a specific task regarding the building/pushing/testing of dockerfiles. Here a short list of them and their respective purposes: -Several images of preCICE are built, based on different systems (Ubuntu 16.04/18.04, Arch Linux) and different specifications -of properties of the image ( root/non-root, package, different MPI versions ). This corresponds to the `Dockerfile.$systemname$.${system_spec}` -Resulting images are then pushed to the [Dockerhub](https://hub.docker.com/u/precice). +- `build_precice.py`: Builds preCICE dockerimages. +- `push_precice.py`: Pushes preCICE dockerimages to DockerHub. +- `build_adapter.py`: Builds adapter dockerimages. +- `push_adapter.py`: Pushes adapter dockerimages to DockerHub. +- `system_testing.py`: Core script for tests. Manages the docker environment for testing and compares output of test to reference using utility scripts. +- `silent_compose.sh`: Utility for `system_testing.py`. Sets up the docker test environment. +- `compare_results.sh`: Utility for `system_testing.py`. Compares textual and numeric data between two folders. +- `push.py`: Utility script that pushes data to `precice_st_output`. Mainly used for storing/accessing reference data when debugging. +- `local_test.py`: Wrapper script for running systemtests on local machine. This is not used by the CI platform. +- `trigger_systemtests.py`: Sends a build request to TravisCI. Mostly used from adapter repositories in order to trigger a build on systemtests. +- `generate_test.py`: Utility script that generates files/directories for a new test. +- `docker.py | common.py`: Modules containing docker-related functions | general functions respectively. Used by other scripts. -## Building solvers -Is done once for every solver, using `Dockerfile.${solver_name}`. +## Building preCICE + +In this stage we pull and install the latest preCICE version from the precice-repository. Since we wish to test multiple operating systems (Ubuntu 18.04/20.04, Arch Linux) and specifications ( install method, MPI version, settings/flags used when installing precice ), we create multiple images with their names specifying the set of architecture and properties used. Images are of the following format: +``` +precice/precice-{architecture}.{property1}.{property2}.{property3}-{precice branch} +``` +For this purpose, we also use different dockerfiles located in the `precice` directory of this repository. These dockerfiles contain arguments we can set at build time to further adjust the installation, meaning that one dockerfile is used for creating mutliple different preCICE images. Names of dockerfiles are formatted as `Dockerfile.{architecture}.{property1}.{property2}.{property3}`. -Resulting images are then stored on the [Dockerhub](https://hub.docker.com/u/precice). +Upon successful build, the resulting images are then pushed to the [Dockerhub/precice](https://hub.docker.com/u/precice). ## Building adapters -To build an adapter we follow a two-stage build, first importing from the preCICE image and then importing from the solver's image -(if the solver's image is actually relevant for building the adapter).We can import from different preCICE base images by specifying `from` +Here, we now start from a baseimage that has preCICE already installed and install a specific adapter on top of it. The adapters all have their own dockerfiles, as they generally have different prerequisites. + +--- +**Important note: building solvers** + +Some adapters require us to install their corresponding solver before beginning the install of the adapter itself. For some versions of the adapters, this can be a quite lengthy process, meaning that we would like to 'skip' this step when building adapters (as this adds unnecessary build time). For this purpose, we sometimes 'pre-build' a dockerimage with the solver installed on it, and then copy the installed solver into our adapter dockerfile when actually building the adapter. The dockerfiles for these pre-installs are stored in the `solver` directory, though note that currently they are not incorporated in the TravisCI building procedure; instead these only need to be built once (usually on a local machine and then pushed to the dockerhub from there) and are only rebuilt when we wish to change the version of the solver. + +Only some of the solver-dockerfiles are currently in use, we decide on a case by case basis if we prefer the decreased build time of using a prebuild solver or the convenience/simplicity of having the adapter-dockerfile install the solver itself. + +--- + +To build an adapter we follow a two-stage build, first importing from the preCICE image and then importing from the solver's image (optional). Which preCICE base image to import from is specified by using the `from` argument during building of the image, e.g: ``` docker build --build-arg from=precice/precice-ubuntu1804.home-develop -d Dockerfile.openfoam-adapter -t openfoam-adapter-ubuntu1804.home-develop . ``` -Note, that due to the fact that each adapter "adapts" differently, the general procedure is slightly different and is outlined below: + +The adapers mostly require different installation methods, below a rough description of how to build each adapter: - **SU2 adapter** - Since the SU2 adapter modifies the SU2 source code, it makes no sense to copy a clean SU2 build, because it will need to be rebuilt. Instead we directly build adapted - SU2 source. + + Since the SU2 adapter modifies the SU2 source code, it makes no sense to copy a clean SU2 build from an external solver image, since we need to rebuild it anyways. Instead, we clone the SU2 source and build it here. Currently, we are using the fixed SU2 version `v6.0.0`. - **deal.II adapter** - deal.II is a library and the adapter just needs to link to it. Thus, we perform the import of deal.II image and only build - the adapter + deal.II is a library and the adapter just needs to link to it. Thus, we import a pre-built deal.II solver image and build only the adapter in the dockerfile. Note that at time of building we are required to set the number of dimensions the adapter is built for. Since we run tests both for 2D- and 3D-scenarios, we have to build two separate adapter images. + - **CalculiX adapter** - We only import the necessary libraries (Spooles, ARPACK), since the CalculiX adapter modifies the CalculiX source code. + We only import the necessary libraries (Spooles, ARPACK), since the CalculiX adapter modifies the CalculiX source code. We use the fixed version `2.16`. + - **OpenFOAM adapter** - Same as for the deal.II adapter. + Since we began using mainly OF v2006, the installation process is now simple enough that we choose to perform it directly in the adapter dockerfile. Prior to this, we were copying OF5 from a solver image. + - **Nutils adapter** - The Nutils adapter is a Python script with Nutils and preCICE for a particular test case. We therefore only provide a Nutils adapter Dockerfile for - the test running stage (not for the building stage). + + The Nutils adapter is simply a Python script with Nutils and preCICE for a particular test case. As a result, there is nothing to be done at this build stage. We only provide a Dockerfile for the running the test in the next stage. - **FEniCS adapter** - We install FEniCS, together with the FEniCS adapter using `Dockerfile.fenics-adapter` file. + We install the FEniCS solver together with the FEniCS adapter when building. + +- **CodeAster adapter** + + Here we again use a prebuilt image of the solver named `precice/codeaster` and only perform the adapter install. -All adapters are built using user `precice` with `gid` and `uid` equal to 1000 (by default) and of `precice` group. As a last building stage they create folder for the file system volume mapping in `/home/precice/Data` folder. -This is done to ensure consistent user rights for writing and reading from mounted directories without a need to use root user on the host system. Running root within container will work, but will lead to output directory being owned by root on host. Running with different users in different directories will cause problems with access to e.g. `/home/precice/Data/Exchange` directory. More information and motivation behind the solution can be found [this blogs post](https://medium.com/@nielssj/docker-volumes-and-file-system-permissions-772c1aee23ca) and [this issue](https://github.com/moby/moby/issues/2259). +All adapters are built by user `precice` with `gid` and `uid` equal to 1000 (by default) and member of the `precice` group. At the end of the install we also create a structure of folders:`/home/precice/Data` and `/home/precice/Logs` in each of the adapters. +This is done to ensure consistent user rights for writing and reading from mounted directories without a need to use root user on the host system. Running root within container *will work*, but will lead to output directory being owned by root on host. Running with different users in different directories will cause problems with access to e.g. `/home/precice/Data/Exchange` directory. More information and motivation behind the solution can be found [this blogs post](https://medium.com/@nielssj/docker-volumes-and-file-system-permissions-772c1aee23ca) and [this issue](https://github.com/moby/moby/issues/2259). ## Running tests At this stage, we spawn containers with the necessary solvers for the simulation. The execution is controlled using [docker-compose](https://docs.docker.com/compose/). Separate volumes are created for the input and the output of every adapter. An additional docker network is created and used for the communication between containers. Exchange of data is done using an additional, common volume. The general pattern across the tests for such volumes are paths -such as `/home/precice/Data/Exchange`, `/home/precice/Data/Input`, `/home/precice/Data/Output`, as explained above. +such as `/home/precice/Data/Exchange`, `/home/precice/Data/Input`, `/home/precice/Data/Output`, which were mentioned above. -The tests are based on the corresponding tutorials from the [tutorials repository](https://github.com/precice/tutorials). Since tests run using independent containers, several modifications are necessary to split the input to solvers in different directories, to adjust the simulated time, or to potentially change a solver's version, as well as to modify the `precice-config.xml` for the communication pattern we use in docker. This is done using the `Dockerfile.tutorial_data` image, which clones the tutorial data and adjusts and splits the input to different solvers. It is then used as the first container spawned by `docker-compose`. +The tests are based on the corresponding tutorials from the [tutorials repository](https://github.com/precice/tutorials). Since tests run using independent containers, several modifications are necessary to split the input to solvers in different directories, to adjust the simulated time, or to potentially change a solver's version, as well as to modify the `precice-config.xml` for the communication pattern we use in docker. This is mainly done using the `Dockerfile.tutorial_data` image, which clones the tutorial data and adjusts the input to different solvers. It is then used as the first container spawned by `docker-compose`, followed by containers for each of the tutorial participants. In general, the test then runs by having the participant containers computing their respective tasks and the `tutorial_data` container serving as central setup location and data storage. -Afterwards, when the simulation finishes, the output is copied from all the solvers into the common volume and is compared to the reference output. An error is thrown if they don't match. +Afterwards, when the simulation finishes, the output is copied from all the solvers into the common volume. The testing script then extracts this data from the docker containers and compares them to the reference output using `compare_results.sh`. An error is thrown if they don't match. -Since it is possible for the output of two identical tests to differ in floating points due to a different machine or OS(as we test different systems and properties), after simple, file by file comparison of the output, -the files are also compared numerically using `compare_results.sh`. This script strips away non-numerical data and then compares files field by field with respect to a specified relative tolerance (default maximum allowed difference is 1 percent) +The comparison goes as follows: +- First, scan the output files to determine if an are missing and if the files differ at all. If the content of a file fully matches its respective reference, it will not be considered in further steps. +- After finding all non-matching files, compare these more thoroughly. There are numerous file differences which we expect to happen; time-stamps, dates, memory adresses, small floating point differences due to running on a different machine or OS. These, however, should not flag a test as failure. The script thus checks the file for textual and numerical differences and filters out any keywords that signify a values we expect to vary beforehand. This then leaves a comparison of filtered text and filtered numbers. For the latter we specifically compute the largest difference observed in a single entry and the overall average of differences. If these exceed their specified relative tolerance (default 0.1 percent), an error is thrown. -In either case after a test finishes, all the related volumes, networks and containers are removed. +In either case, after a test finishes, all the related volumes, networks and containers are removed. diff --git a/docs/development.md b/docs/development.md index f2a7e784f..3cb2c665c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,19 +1,32 @@ -# Useful documentation +# Tips/Tricks for using systemtests -* [Docker](https://docs.docker.com/) -* [Docker-compose](https://docs.docker.com/compose/) -* [Main Travis docs](https://docs.travis-ci.com/) -* [Travis API](https://developer.travis-ci.com/) +This file contains small guidelines on what to do if you encounter some of the more common problems. Before reading this, one should make sure to read the other docs and/or be familiar with the code. +## Useful Documentation -# Useful patterns and commands -## During development of standalone Dockerfiles +See main [README.md](./README.md) under `Where to start`. -If something fails during building, you can determine the failing command and comment out the remaining of the Dockerfile. Then, rebuild and tag (e.g. `test_image`). You can then interactively try to follow the commented out section of the Dockerfile, by starting the container interactively: +## Foreford: deciding where to run your builds +Whenever you detect a build failure and start investigating the failing command, it is recommended to make use of local builds (on your machine) as much as possible (as opposed to sending builds to the CI platform). This way you have much more interactive control over the test (e.g. being able to enter an active docker container to figure things out at runtime) and save computational resources on the platform that others might want to use. Nontheless, do not be afraid to use CI when necessary, sometimes an issue can only be resolved by checking how a certain build behaves in CI. + +Note that the investigation methods below (whereby you interact with images/containers through a shell) require you to run the build locally. + +## Investigating failures during the build stage of Dockerfiles +If something fails during building, you will be able to find the failing command in the logging output during building (Docker will print each line in the Dockerfile that it is about to execute). For debugging, you can then comment out all commands of the Dockerfile below **and including** the failing line. Then, rebuild the image (possibly tag it something distinct so that it doesn't interfere with actual functional Dockerfiles, e.g. `debug_fenics-adapter`). This will yield an intact docker image that you can then enter in interactive mode to check its status prior to failing and execute the failing command manually to see whats going on. To launch such an image interactively, see this command using the aforementioned example: ``` - docker run -it --rm test_image /bin/bash +docker run -it --rm debug_fenics-adapter /bin/bash +``` +The `-it` flags will cause you to enter a shell with which to interact with the target image. `/bin/bash` specifies the shell, `--rm` is an optional flag that ensures that the container will be removed after you exit it. + +## Investigating failures during runtime of a docker-compose test +If failures occur during the runtime of a test (meaning the execution of a tutorial example using finished adapter Dockerfiles), the error most likely is happening during the execution of commands specified in `docker-compose.yml` and not whilst building a Dockerimage. In this case, you can hijack the running containers mid-test with the following: ``` -Usually it is much easier to debug in this way. +docker exec -it id_of_target_container /bin/bash +``` +Note that the ID of the wanted container is required, which you can obtain through `docker container ls`. +This allows you to interact with test participants through a shell while they are executing their specified docker-compose commands, which can be useful to identify issues that pop up during computation. Beware that by default, the container shuts down after it ends its command chain (from the docker-compose file) either through success or error, which will terminate your connection. A workaround in this case is to add a temporary sleep command, e.g. `sleep 10m`, at a fitting location in the launch commands. + + If you are developing a new base image for preCICE, make sure you create a user `precice`, in group `precice` with `uid` and `gid` equal to 1000, as done in other base dockerfiles. Additionally, make sure that precice in installed in `/home/precice/precice`, and create folders `/home/precice/Data/Exchange`, @@ -38,7 +51,7 @@ owned by user `precice`, not the `root` user and not the user of your local mach You should also make sure that running both on a local and a remote machine work, testing both `local_test.py` and `system_testing.py` with the considered test case. -## If something fails on Travis +## If something fails on TravisCI 1. Inspect the build log 2. Restart the build (maybe it is a connection problem) @@ -50,7 +63,7 @@ You should also make sure that running both on a local and a remote machine work ## If a systemtest request fails with 'HTTP Error 403: Forbidden' -It might happen at some point that the `trigger_systemtests.py` script responsible for triggering builds through the Travis API starts to fail with the error above. This could happen due to the `TRAVIS_ACCESS_TOKEN` expiring and is potentially easy to fix. To renew the token, generate a new one locally using the Travis CLI (taken from [here](https://blog.travis-ci.com/2013-01-28-token-token-token)): +It might happen at some point that the `trigger_systemtests.py` script responsible for triggering builds through the Travis API starts to fail with the error above. This could happen due to the `TRAVIS_ACCESS_TOKEN` expiring after some time and is potentially easy to fix. To renew the token, generate a new one locally using the Travis CLI (taken from [here](https://blog.travis-ci.com/2013-01-28-token-token-token)): ``` gem install travis && travis login && travis token @@ -60,23 +73,23 @@ and replace the current `TRAVIS_ACCESS_TOKEN` value in the TravisCI systemtests ## If there are network problems -It can happen, that you cannot access the network from the inside of docker. You can try to fix it using `--network=host` during build of docker images or by specifying `network: host` in the `docker-compose.yml`. You might also want to add this parameter in `build_image` function in `docker.py`. +It might happen that you cannot access the network from inside of docker. You can try to fix it using `--network=host` during build of docker images or by specifying `network: host` in the `docker-compose.yml`. You might also want to add this parameter in `build_image` function in `docker.py`. ## If CI on adapters does not work -You first need to add `TRAVIS_ACCESS_TOKEN` as environment variable on your system. -Then you can run and check the generated JSON file without sending a request +For locally investigating this issue, make sure you have a `TRAVIS_ACCESS_TOKEN` stored as environment variable on your system. +Then you can then run and check the generated JSON file without sending an actual request to the server with: ``` python3 trigger_systemtests.py --adapter su2 --test ``` -If it looks fine, you can run it without `--test` to actually send the request to Travis. Then check the triggered builds. -If there are no builds visible there, check the `requests` section of Travis, maybe Travis could not interpret the request correctly. +If it looks fine, you can run it without `--test` to actually send the request to Travis. Then check in the Travis dashboard if a build was launched. +If not, you should at least be able to see the received request under `requests` section of Travis together with an explanation why the build was denied. ## If you want to use Dockerfiles for your own development Some users might want to run coupled simulations without having everything installed on the same system. -For instance mount input folders from your machine to `/home/precice/Data/Input` in the container and get output from +For instance: mount input folders from your machine to `/home/precice/Data/Input` in the container and get output from `/home/precice/Data/Output`. With the provided setup and a few tweaks this is easy to achieve. Using the example of the fenics-adapter: @@ -102,13 +115,13 @@ Then you are free to run your coupled simulation for each participant with: ``` docker run --user=precice -it -v $(pwd)/HT/partitioned-heat/fenics-fenics:/home/precice/Data/Input -v exchange:/home/precice/Data/Exchange fenics-adapter-user /bin/bash``` ``` -Output can then be copied from the containers. +Output can then be copied from the containers afterwards. ## If you want to run the tests based on code from a non-default branch -Depending on the test case several code components are used (preCICE, bindings, adapter(s), tutorial). Sometimes it becomes necessary to use a branch that is different from the one that is used as default (e.g. `develop` is used for the preCICE images. See [here](https://github.com/precice/systemtests/blob/ec4ef9d4aedd0087dfb3a8ed98fdf7a1267c7751/precice/Dockerfile.Ubuntu1604.home#L50-L52)). +Depending on the test case several code components are used (preCICE, bindings, adapter(s), tutorial). Sometimes it becomes necessary to use a branch different from the default (e.g. `develop` is used for the preCICE images. See [here](https://github.com/precice/systemtests/blob/ec4ef9d4aedd0087dfb3a8ed98fdf7a1267c7751/precice/Dockerfile.Ubuntu1604.home#L50-L52)). -### Non-default branch for preCICE +### Non-default branch for preCICE If you want to use a different branch for the preCICE image, you can just use the [`--branch` option](https://github.com/precice/systemtests/blob/master/system_testing.py#L178) when you run `system_testing.py`. @@ -116,10 +129,10 @@ If you want to use a different branch for the preCICE image, you can just use th For other components we do not have a nice interface (see https://github.com/precice/systemtests/issues/121). However, there is a workaround: -We want to use the branch `feature` of the FEniCS adapter instead of the default branch `master` for the test `fe-fe`. We only want to run the test locally on our machine. +We want to use the branch `feature` of the FEniCS adapter instead of the default branch `master` for the test `fe-fe`. We only want to run the test locally on our machine. 1. We have to modify the `Dockerfile` correspondingly to use the branch `feature`. -2. Make sure that the modified `Dockerfile` is used to build the image `precice/fenics-adapter-ubuntu1804.home-develop`. +2. Make sure that the modified `Dockerfile` is used to build the image `precice/fenics-adapter-ubuntu1804.home-develop`. ``` $ docker image build -t precice/fenics-adapter-ubuntu1804.home-develop -f Dockerfile.fenics-adapter --build-arg from=precice/precice-ubuntu1804.home-develop . ``` From 5712064d7e1f08fe9269d00462841d1380709163 Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 22 Dec 2020 10:48:39 +0100 Subject: [PATCH 07/10] Capitalize FEniCS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Benjamin Rüth --- adapters/Dockerfile.fenics-adapter | 1 + 1 file changed, 1 insertion(+) diff --git a/adapters/Dockerfile.fenics-adapter b/adapters/Dockerfile.fenics-adapter index 82b90ca5d..ced071aa1 100644 --- a/adapters/Dockerfile.fenics-adapter +++ b/adapters/Dockerfile.fenics-adapter @@ -23,6 +23,7 @@ RUN wget -q https://bootstrap.pypa.io/get-pip.py -O get-pip.py && \ python3 get-pip.py +# Install FEniCS RUN add-apt-repository -y ppa:fenics-packages/fenics && \ apt-get -qq update && \ apt-get -qq install --no-install-recommends fenics && \ From a1b8940785cdd33f83eaece9ea4ae37477a5a6e9 Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 22 Dec 2020 11:00:12 +0100 Subject: [PATCH 08/10] Install & upgrade pip in adapter dockerfile --- adapters/Dockerfile.fenics-adapter | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/adapters/Dockerfile.fenics-adapter b/adapters/Dockerfile.fenics-adapter index ced071aa1..6b5ad932b 100644 --- a/adapters/Dockerfile.fenics-adapter +++ b/adapters/Dockerfile.fenics-adapter @@ -14,14 +14,10 @@ RUN apt-get -qq update && apt-get -qq install \ apt-utils && \ apt-get -qq install \ software-properties-common \ - python3 \ - python3-dev && \ + python3-dev \ + python3-pip && \ rm -rf /var/lib/apt/lists/* -# Install pip dependecies; we have to use pip, since cython provided by apt-get is too old. -RUN wget -q https://bootstrap.pypa.io/get-pip.py -O get-pip.py && \ - python3 get-pip.py - # Install FEniCS RUN add-apt-repository -y ppa:fenics-packages/fenics && \ @@ -29,7 +25,9 @@ RUN add-apt-repository -y ppa:fenics-packages/fenics && \ apt-get -qq install --no-install-recommends fenics && \ rm -rf /var/lib/apt/lists/* - +# Upgrade pip to newest version (pip version from 18.04 apt-get is outdated) +RUN pip3 install --user --upgrade pip +# Use pip to install cython (apt-get version of cython is too old) RUN pip3 install --user cython # TODO: can we put this dependency into requirements.txt of python? USER precice From a431b509570d628b9cba5f09dc84c2c8ac680f8a Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 22 Dec 2020 11:00:30 +0100 Subject: [PATCH 09/10] Remove pip installs in precice dockerfiles --- precice/Dockerfile.Ubuntu1804.home | 4 ---- precice/Dockerfile.Ubuntu1804.package | 4 ---- precice/Dockerfile.Ubuntu2004.home | 1 - precice/Dockerfile.Ubuntu2004.package | 1 - 4 files changed, 10 deletions(-) diff --git a/precice/Dockerfile.Ubuntu1804.home b/precice/Dockerfile.Ubuntu1804.home index b2a35d95d..bb157fec6 100644 --- a/precice/Dockerfile.Ubuntu1804.home +++ b/precice/Dockerfile.Ubuntu1804.home @@ -14,7 +14,6 @@ RUN apt-get -qq update && apt-get -qq install \ git \ python3-numpy \ python3-dev \ - python3-pip \ petsc-dev \ wget \ bzip2 \ @@ -47,9 +46,6 @@ RUN chown -R precice:precice /petsc USER precice -# Upgrade pip to latest version -RUN pip3 install --user --upgrade pip - # Rebuild image from here on if `force_rebuild` is enabled ARG CACHEBUST diff --git a/precice/Dockerfile.Ubuntu1804.package b/precice/Dockerfile.Ubuntu1804.package index f85587f4a..188ccb266 100644 --- a/precice/Dockerfile.Ubuntu1804.package +++ b/precice/Dockerfile.Ubuntu1804.package @@ -14,7 +14,6 @@ RUN apt-get -qq update && apt-get -qq install \ git \ python3-numpy \ python3-dev \ - python3-pip \ petsc-dev \ wget \ bzip2 \ @@ -46,9 +45,6 @@ RUN apt-get -qq update && apt-get -qq install \ # Rebuild image if force_rebuild after that command ARG CACHEBUST - # Upgrade pip to latest version - RUN pip3 install --user --upgrade pip - USER precice WORKDIR /home/precice # Setting some environment variables for installing preCICE diff --git a/precice/Dockerfile.Ubuntu2004.home b/precice/Dockerfile.Ubuntu2004.home index bb8dc4c9b..49beb7d1c 100644 --- a/precice/Dockerfile.Ubuntu2004.home +++ b/precice/Dockerfile.Ubuntu2004.home @@ -17,7 +17,6 @@ RUN apt-get -qq update && apt-get -qq install \ git \ python3-numpy \ python3-dev \ - python3-pip \ petsc-dev \ wget \ bzip2 \ diff --git a/precice/Dockerfile.Ubuntu2004.package b/precice/Dockerfile.Ubuntu2004.package index b3cc1650a..c161549e1 100644 --- a/precice/Dockerfile.Ubuntu2004.package +++ b/precice/Dockerfile.Ubuntu2004.package @@ -18,7 +18,6 @@ RUN apt-get -qq update && apt-get -qq install \ git \ python3-dev \ python3-numpy \ - python3-pip \ petsc-dev \ wget \ bzip2 \ From de6901e62bef156d587429104d7efad65ced9007 Mon Sep 17 00:00:00 2001 From: Eder-K Date: Tue, 22 Dec 2020 11:07:45 +0100 Subject: [PATCH 10/10] Merge develop into EderK-patch-pip --- .travis.yml | 6 +++--- precice/Dockerfile.Ubuntu1804.home | 6 ++---- precice/Dockerfile.Ubuntu1804.package | 2 +- 3 files changed, 6 insertions(+), 8 deletions(-) diff --git a/.travis.yml b/.travis.yml index 29f1cf932..1cd50407c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -129,21 +129,21 @@ jobs: - python push_adapter.py --dockerfile adapters/Dockerfile.codeaster-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push.py - - name: "[18.04] CalculiX adapter [failure allowed]" + - name: "[18.04] CalculiX adapter" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation package --docker-username $DOCKER_USERNAME - python push.py - - name: "[18.04] CalculiX adapter [PETSc] [failure allowed]" + - name: "[18.04] CalculiX adapter [PETSc]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation home --petsc yes --docker-username $DOCKER_USERNAME - python push_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu1804 --precice-installation home --petsc yes --docker-username $DOCKER_USERNAME - python push.py - - name: "[20.04] CalculiX adapter [PETSc] [failure allowed]" + - name: "[20.04] CalculiX adapter [PETSc]" if: fork = false script: - python build_adapter.py --dockerfile adapters/Dockerfile.calculix-adapter --operating-system ubuntu2004 --precice-installation package --petsc yes --docker-username $DOCKER_USERNAME diff --git a/precice/Dockerfile.Ubuntu1804.home b/precice/Dockerfile.Ubuntu1804.home index 2973d9c99..9d446042e 100644 --- a/precice/Dockerfile.Ubuntu1804.home +++ b/precice/Dockerfile.Ubuntu1804.home @@ -43,12 +43,10 @@ RUN wget -nv 'https://www.mcs.anl.gov/petsc/mirror/release-snapshots/petsc-3.12. make all test RUN chown -R precice:precice /petsc - -USER precice - -# Rebuild image from here on if `force_rebuild` is enabled +# Rebuild image if force_rebuild after that command ARG CACHEBUST +USER precice WORKDIR /home/precice # Setting some environment variables for installing preCICE ENV CPLUS_INCLUDE_PATH="$CPLUS_INCLUDE_PATH:/usr/include/eigen3" \ diff --git a/precice/Dockerfile.Ubuntu1804.package b/precice/Dockerfile.Ubuntu1804.package index a5c3c7156..ab39836c0 100644 --- a/precice/Dockerfile.Ubuntu1804.package +++ b/precice/Dockerfile.Ubuntu1804.package @@ -11,10 +11,10 @@ RUN apt-get -qq update && apt-get -qq install \ libboost-all-dev \ libeigen3-dev \ libxml2-dev \ + petsc-dev \ git \ python3-numpy \ python3-dev \ - petsc-dev \ wget \ bzip2 \ cmake && \