From 650b35398031e59fc397b8bc0e149c91a2a7eb64 Mon Sep 17 00:00:00 2001 From: Philipp Ross Date: Tue, 3 May 2022 14:47:56 +0200 Subject: [PATCH] Added Dockerfile, workflow and documentation to run QUARK as a container. Co-authored-by: Martin Meilinger --- .github/workflows/container_build_publish.yml | 58 +++++++++++++++++++ .gitignore | 1 + Dockerfile | 6 ++ README.md | 40 +++++++++++++ docs/tutorial.rst | 51 ++++++++++++++++ 5 files changed, 156 insertions(+) create mode 100644 .github/workflows/container_build_publish.yml create mode 100644 Dockerfile diff --git a/.github/workflows/container_build_publish.yml b/.github/workflows/container_build_publish.yml new file mode 100644 index 00000000..1e19004c --- /dev/null +++ b/.github/workflows/container_build_publish.yml @@ -0,0 +1,58 @@ +# 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', 'dockerSupport'] + +# 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 + # 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@65b78e6e13532edd9afa3aa52ac7964289d1a9c1 + 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@f2a1d5e99d037542a71f64918e516c093c6f3fc4 + 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 }} diff --git a/.gitignore b/.gitignore index 94a5605e..89c7a5e5 100644 --- a/.gitignore +++ b/.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/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..9944cbb7 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,6 @@ +FROM python:3.9 + +COPY . . +RUN pip install -r .settings/requirements_full.txt + +ENTRYPOINT ["python", "src/main.py"] diff --git a/README.md b/README.md index fe1fa4af..4b80ed80 100644 --- a/README.md +++ b/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 created container: +``` +docker run -it --rm quark +``` + +You can also build the docker image locally like: +``` +docker build -t 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 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: diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 73efc331..4c353243 100644 --- a/docs/tutorial.rst +++ b/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 created container: + +:: + + docker run -it --rm quark + +You can also build the docker image locally like: + +:: + + docker build -t 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 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^