Added Dockerfile, workflow and documentation to run QUARK as a contai…

…ner. (#85)

Co-authored-by: Philipp Ross <[email protected]>
Co-authored-by: Martin Meilinger <[email protected]>

.github/workflows/container_build_publish.yml

@@ -0,0 +1,62 @@
+# Based on https://docs.github.com/en/actions/publishing-packages/publishing-docker-images
+name: Create and publish a QUARK Docker image
+
+# Configures this workflow to run every time a change is pushed to the branch called `main` or `dev`.
+on:
+  push:
+    branches: ['main', 'dev']
+
+# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
+jobs:
+  build-and-push-image:
+    if: github.repository == 'QUARK-framework/QUARK'
+    runs-on: ubuntu-latest
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: write
+      #
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      # Uses the `docker/login-action` action to log in to the Container registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=schedule
+            type=ref,event=branch
+            type=ref,event=tag
+            type=ref,event=pr
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha
+      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
+      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          #  Start with a limited number of platforms
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -310,5 +310,6 @@ $RECYCLE.BIN/
 # End of https://www.toptal.com/developers/gitignore/api/pycharm,macos,windows,python
 /benchmark_runs/
 /.idea/
+/config.yml
 /.settings/active_env.json
 /.settings/envs/

Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.9
+
+COPY . .
+RUN pip install -r .settings/requirements_full.txt
+
+ENTRYPOINT ["python", "src/main.py"]

README.md

@@ -152,6 +152,46 @@ application:
 repetitions: 1
 ```
 
+### Run as Container
+We also support the option to run the framework as a container.
+After making sure your docker daemon is running, you can run the container:
+```
+docker run -it --rm ghcr.io/quark-framework/quark
+```
+
+You can also build the docker image locally like:
+``` 
+docker build -t ghcr.io/quark-framework/quark .
+```
+
+In case you want to use a config file you have to add it to the docker run command: 
+```
+-v /Users/alice/desktop/my_config.yml:/my_config.yml
+```
+`/Users/alice/desktop/my_config.yml` specifies the QUARK config file on your local machine.
+Then you can run the docker container with the config:
+```
+docker run -it --rm  -v /Users/alice/desktop/my_config.yml:/my_config.yml ghcr.io/quark-framework/quark --config my_config.yml
+```
+
+In case you want to access the benchmark run folder afterwards, you can attach a volume to the run command:
+```
+-v /Users/alice/desktop/benchmark_runs:/benchmark_runs/
+```
+The results of the benchmark run are then stored to a new directory in `/Users/alice/desktop/benchmark_runs`.
+
+In case you have local proxy settings you can add the following flags to the run command:
+
+```
+-e http_proxy=$http_proxy -e https_proxy=$https_proxy -e HTTP_PROXY=$HTTP_PROXY -e HTTPS_PROXY=$HTTPS_PROXY
+```
+
+AWS credentials can be mounted to the run command like:
+```
+-v $HOME/.aws/:/root/.aws:ro
+```
+
+
 
 #### Summarizing Multiple Existing Experiments
 You can also summarize multiple existing experiments like this:

docs/tutorial.rst

@@ -170,6 +170,57 @@ Example for a config file:
 One handy thing to do is to use the interactive mode once to create a config file.
 Then you can change the values of this config file and use it to start the framework.
 
+
+Run as Container
+^^^^^^^^^^^^^^^^
+We also support the option to run the framework as a container.
+After making sure your docker daemon is running, you can run the container:
+
+::
+
+    docker run -it --rm ghcr.io/quark-framework/quark
+
+You can also build the docker image locally like:
+
+::
+
+    docker build -t ghcr.io/quark-framework/quark .
+
+In case you want to use a config file you have to add it to the docker run command:
+
+::
+
+    -v /Users/alice/desktop/my_config.yml:/my_config.yml
+
+
+"/Users/alice/desktop/my_config.yml" specifies the QUARK config file on your local machine.
+Then you can run the docker container with the config:
+
+::
+
+    docker run -it --rm  -v /Users/alice/desktop/my_config.yml:/my_config.yml  ghcr.io/quark-framework/quark --config my_config.yml
+
+In case you want to access the benchmark run folder afterwards, you can attach a volume to the run command:
+
+::
+
+    -v /Users/alice/desktop/benchmark_runs:/benchmark_runs/
+
+The results of the benchmark run are then stored to a new directory in `/Users/alice/desktop/benchmark_runs`.
+
+In case you have local proxy settings you can add the following flags to the run command:
+
+::
+
+    -e http_proxy=$http_proxy -e https_proxy=$https_proxy -e HTTP_PROXY=$HTTP_PROXY -e HTTPS_PROXY=$HTTPS_PROXY
+
+AWS credentials can be mounted to the run command like:
+
+::
+
+    -v $HOME/.aws/:/root/.aws:ro
+
+
 Summarizing Multiple Existing Experiments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^