Difference between revisions of "Installation/Ansible"

From OpenFOAMWiki
m (Add clone command for BitBucket)
(Add link to the Docker Hub page)
Line 31: Line 31:
 
</bash>
 
</bash>
 
on the command line
 
on the command line
 +
 +
== Building Docker Images ==
 +
 +
This project can also be used to build docker containers. The programmer has to write a playbook that says which base image to use, which OpenFOAM-version to compile and then an image is built (intermediate files are removed to keep the image reasonable small). An example script is provided. So for instance
 +
<bash>
 +
ansible-playbook exampleConfigs/buildContainer.yml --extra-vars="base_container=centos8 container_distro=p1912"
 +
</bash>
 +
builds an image based on the CentOS 8  image that that has OpenFOAM v1912.
 +
 +
For a full description have a look at the Chapter ''Building docker images'' in  [https://sourceforge.net/p/openfoam-extend/ansibleFoamInstallation/ci/default/tree/README.md the README].
 +
 +
=== Using the images ===
 +
 +
The images are built in such a way that it is easy to work with cases that are on the local file-system. The <tt>runFoamContainer.sh</tt> script that comes with the sources does this: it starts the specified image and mounts the current directory on the host machine to a directory <tt>/foamdata</tt> in which a shell is started (so the user can start working immediately). Without arguments it lists all locally available images that were built with Ansible.
 +
 +
This is the script (it only needs Docker to be installed on your Linux-machine):
 +
 +
<bash>
 +
#! /bin/bash
 +
 +
# This runs a Foam-container and mounts the current working directory
 +
 +
if [ "$#" -lt 1 ]; then
 +
    echo "Start with image and current directory: $0 <image>"
 +
    echo "Start with image and specified directory: $0 <image> <directory> "
 +
    echo
 +
    echo "Proper images"
 +
    echo
 +
    docker images --filter "label=ofansible.foamarch"
 +
    exit 0
 +
fi
 +
 +
username="$USER"
 +
user="$(id -u)"
 +
imageName=$1
 +
home="${2:-$(pwd)}"
 +
containerName="${imageName//[\/\:]/_}_run"
 +
 +
docker run  -it --name "${containerName}" -e HOST_USER_ID=$(id -u) -e HOST_USER_GID=$(id -g) -e QT_X11_NO_MITSHM=1 -e DISPLAY="${DISPLAY}" --rm --volume="${home}:/foamdata"  -v=/tmp/.X11-unix:/tmp/.X11-unix  "${imageName}"
 +
</bash>
 +
 +
=== Pre-built images ===
 +
 +
Some images built with Ansible are published [https://hub.docker.com/repository/docker/bgschaid/openfoam_by_ansible on Dockerhub]. For a complete list see [https://hub.docker.com/repository/registry-1.docker.io/bgschaid/openfoam_by_ansible/tags?page=1 this list]. The names of the images are composed of
 +
* the base image
 +
* the OpenFOAM-version
 +
* additional software (currently all the iamges have  [[Contrib/PyFoam|PyFoam]]  so it is not mentioned)
 +
 +
For instance to pull and start an image based on Ubuntu 18.04 with OpenFOAM v1912 and [[Contrib/swak4Foam|swak4foam]] the script is used like this
 +
<bash>
 +
./runFoamContainer.sh bgschaid/openfoam_by_ansible:ubuntu1804_with_p1912_init_and_swak4foam
 +
</bash>
 +
 +
The images do '''not''' have ParaView installed
 +
 +
Feel free to use the images as a basis for your own images by customizing them with Ansible or DockerFiles
  
 
== Other ==
 
== Other ==

Revision as of 23:07, 28 May 2020

The aim of this project is to automatically build OpenFOAM-variants from source using the tool Ansible. The script installs all the requirements before attempting to compile OpenFOAM

The full description can be found in this subproject in OpenFOAM-extend.

The only requirements for this script to work are Mercurial (for getting the sources) and Ansible. They should be installed through the

1 Basic Usage

First get the sources:

 
hg clone http://hg.code.sf.net/p/openfoam-extend/ansibleFoamInstallation
cd ansibleFoamInstallation

Then a playbook with the requirements has to be edited. There is already an example playbook that builds three different Foam versions with cfMesh and swak4foam and also installs PyFoam :

 
sudo ansible-playbook exampleConfigs/allFoams.yml

On a supported Linux this makes sure that all the required packages are installed, it pulls the required sources and builds them (this may take a couple of hours)

To install only a single FOAM-distro (in this example OpenFOAM+ v1706) call

 
sudo ansible-playbook exampleConfigs/fullInstall.yml --extra-vars=distro=p1706

For further information see the latest Version of the README

1.1 Development version

To get to the latest development version do

 
hg update develop

on the command line

2 Building Docker Images

This project can also be used to build docker containers. The programmer has to write a playbook that says which base image to use, which OpenFOAM-version to compile and then an image is built (intermediate files are removed to keep the image reasonable small). An example script is provided. So for instance

 
ansible-playbook exampleConfigs/buildContainer.yml --extra-vars="base_container=centos8 container_distro=p1912"

builds an image based on the CentOS 8 image that that has OpenFOAM v1912.

For a full description have a look at the Chapter Building docker images in the README.

2.1 Using the images

The images are built in such a way that it is easy to work with cases that are on the local file-system. The runFoamContainer.sh script that comes with the sources does this: it starts the specified image and mounts the current directory on the host machine to a directory /foamdata in which a shell is started (so the user can start working immediately). Without arguments it lists all locally available images that were built with Ansible.

This is the script (it only needs Docker to be installed on your Linux-machine):

 
#! /bin/bash
 
# This runs a Foam-container and mounts the current working directory
 
if [ "$#" -lt 1 ]; then
    echo "Start with image and current directory: $0 <image>"
    echo "Start with image and specified directory: $0 <image> <directory> "
    echo
    echo "Proper images"
    echo
    docker images --filter "label=ofansible.foamarch"
    exit 0
fi
 
username="$USER"
user="$(id -u)"
imageName=$1
home="${2:-$(pwd)}"
containerName="${imageName//[\/\:]/_}_run"
 
docker run  -it --name "${containerName}" -e HOST_USER_ID=$(id -u) -e HOST_USER_GID=$(id -g) -e QT_X11_NO_MITSHM=1 -e DISPLAY="${DISPLAY}" --rm --volume="${home}:/foamdata"  -v=/tmp/.X11-unix:/tmp/.X11-unix  "${imageName}"

2.2 Pre-built images

Some images built with Ansible are published on Dockerhub. For a complete list see this list. The names of the images are composed of

  • the base image
  • the OpenFOAM-version
  • additional software (currently all the iamges have PyFoam so it is not mentioned)

For instance to pull and start an image based on Ubuntu 18.04 with OpenFOAM v1912 and swak4foam the script is used like this

 
./runFoamContainer.sh bgschaid/openfoam_by_ansible:ubuntu1804_with_p1912_init_and_swak4foam

The images do not have ParaView installed

Feel free to use the images as a basis for your own images by customizing them with Ansible or DockerFiles

3 Other

A backup-version of the repository can be found at on BitBucket. It can be cloned with

 
hg clone https://bitbucket.org/bgschaid/ansiblefoaminstallation