218 create docker image (#232)

* add github action to build docker images

* update readme

* use docker hub by default

.github/workflows/build-and-push-docker.yml

@@ -0,0 +1,81 @@
+name: build and push docker
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+    branches:
+      - build-docker-image
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v3
+      -
+        name: Decide the docker image version number
+        run: |
+            if [[ -f ./docker/build-docker-image-version.txt ]]; then
+              echo "DOCKER_IMAGE_TAG=$( tail -n 1 ./docker/build-docker-image-version.txt )" >> $GITHUB_ENV
+            else
+              echo "DOCKER_IMAGE_TAG=${{ github.ref_name }}" >> $GITHUB_ENV
+            fi
+            echo ${{ env.DOCKER_IMAGE_TAG }}
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      -
+        name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - 
+        name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      -
+        name: Build and push gplately amd64
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./docker/Dockerfile
+          push: true
+          platforms: linux/amd64
+          provenance: false
+          tags: |
+            gplates/gplately:amd64-${{ env.DOCKER_IMAGE_TAG }}
+            ghcr.io/gplates/gplately:amd64-${{ env.DOCKER_IMAGE_TAG }} 
+      -
+        name: Build and push gplately arm64
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./docker/Dockerfile
+          push: true
+          platforms: linux/arm64
+          provenance: false
+          tags: |
+            gplates/gplately:arm64-${{ env.DOCKER_IMAGE_TAG }}
+            ghcr.io/gplates/gplately:arm64-${{ env.DOCKER_IMAGE_TAG }}
+      -
+        name: Create cross-platform images
+        run: |
+            docker buildx imagetools create -t gplates/gplately:${{ env.DOCKER_IMAGE_TAG }} gplates/gplately:amd64-${{ env.DOCKER_IMAGE_TAG }} gplates/gplately:arm64-${{ env.DOCKER_IMAGE_TAG }}
+            docker buildx imagetools create -t ghcr.io/gplates/gplately:${{ env.DOCKER_IMAGE_TAG }} ghcr.io/gplates/gplately:amd64-${{ env.DOCKER_IMAGE_TAG }} ghcr.io/gplates/gplately:arm64-${{ env.DOCKER_IMAGE_TAG }}
+      -     
+        name: Create the latest tags
+        if: 
+        run: |
+            if [[ -f ./docker/build-docker-image-version.txt ]]; then
+              docker buildx imagetools create -t gplates/gplately:latest gplates/gplately:amd64-${{ env.DOCKER_IMAGE_TAG }} gplates/gplately:arm64-${{ env.DOCKER_IMAGE_TAG }}
+              docker buildx imagetools create -t ghcr.io/gplates/gplately:latest ghcr.io/gplates/gplately:amd64-${{ env.DOCKER_IMAGE_TAG }} ghcr.io/gplates/gplately:arm64-${{ env.DOCKER_IMAGE_TAG }} 
+            fi

README.md

@@ -112,6 +112,14 @@ git pull # fetch all recent changes from this branch
 pip install .
 ```
 
+### 3. Using Docker 🐳
+
+- `docker pull gplates/gplately`
+- `docker run --rm -ti -p 8888:8888  gplates/gplately`
+- http://localhost:8888
+
+See details [docker/README.md](docker/README.md).
+
 ## Usage
 
 GPlately uses objects to accomplish a variety of common tasks. The common objects include:
@@ -146,7 +154,7 @@ gDownload = gplately.DataServer("Muller2019")
 rotation_model, topology_features, static_polygons = gDownload.get_plate_reconstruction_files()
 ```
 
-### The `PlateModelManager` object
+### The `PlateModelManager` object 🚀
 
 ... was introduced as an alternative/substitute to the `DataServer` object. The `PlateModelManager` object can be used to download and manage plate reconstruction models.
 

docker/Dockerfile

@@ -0,0 +1,38 @@
+#
+# to build this docker container image
+# step 1: git clone https://github.com/GPlates/gplately.git
+# step 2: cd gplately
+# step 3: docker build -f docker/Dockerfile -t gplately .
+#
+# run the docker container
+# docker run --rm -ti -p 8888:8888 -v `pwd`:/workspace/my_stuff gplately 
+#
+
+# if error, try with --no-cache option
+
+FROM mambaorg/micromamba:1.5.8
+
+LABEL org.opencontainers.image.authors="michael.chin@sydney.edu.au"
+LABEL version="v1.3.0"
+
+USER root
+RUN apt-get update && apt-get install ffmpeg libsm6 libxext6  -y
+
+USER $MAMBA_USER
+COPY --chown=$MAMBA_USER:$MAMBA_USER ./docker/env.yaml /tmp/env.yaml
+RUN micromamba install -y -n base -f /tmp/env.yaml && \
+    micromamba clean --all --yes
+
+ARG MAMBA_DOCKERFILE_ACTIVATE=1 
+
+COPY --chown=$MAMBA_USER:$MAMBA_USER . /tmp/gplately
+RUN pip3 install /tmp/gplately
+RUN rm -rf /tmp/gplately
+
+COPY --chown=$MAMBA_USER:$MAMBA_USER ./Notebooks /workspace/Notebooks
+
+WORKDIR /workspace
+
+EXPOSE 8888
+
+CMD ["jupyter", "notebook", "--no-browser", "--ip=0.0.0.0", "--NotebookApp.token=''"]

docker/README.md

@@ -0,0 +1,26 @@
+### 👉 pull the docker image from Docker Hub or ghcr.io
+
+- `docker pull ghcr.io/gplates/gplately`
+- `docker pull gplates/gplately`
+
+###  👉 build the docker image
+
+- step 1: `git clone --depth 1 --branch master https://github.com/GPlates/gplately.git`
+- step 2: `cd gplately`
+- step 3: `docker build -f docker/Dockerfile -t gplately .`
+
+Note: if errors occur, try build with **--no-cache** option
+
+### 👉 run the docker container
+
+```docker run --rm -ti -p 8888:8888 -v `pwd`:/workspace/my_stuff gplately```
+
+### 👉 build and push docker images to Docker Hub and ghcr.io
+
+- option 1: create and push a tag (will trigger the github action)
+- option 2: 
+    - step 1: create a branch `build-docker-image` (based on master or whatever branch you like)
+    - step 2: update the version info in docker/build-docker-image-version.txt
+    - step 3: push the change in step 2 (will trigger the github action)
+    - note: this will also create the `latest` tag
+

docker/build-docker-image-version.txt

@@ -0,0 +1,4 @@
+# this file is used to control the docker image version tag.
+# only the last line has effect.
+
+v1.3.0

docker/env.yaml

@@ -0,0 +1,9 @@
+name: base
+channels:
+  - conda-forge
+dependencies:
+  - python=3.11
+  - pip
+  - gplately 
+  - jupyter
+  - moviepy