From fc4089e4aef701031cbddd441bc40e772ddcd0f0 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 29 Sep 2021 11:27:36 +0200 Subject: [PATCH 01/18] Add initial Dockerfile --- .dockerignore | 9 +++++++++ .gitignore | 2 ++ Dockerfile | 10 ++++++++++ 3 files changed, 21 insertions(+) create mode 100644 .dockerignore create mode 100644 .gitignore create mode 100644 Dockerfile diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..811eada --- /dev/null +++ b/.dockerignore @@ -0,0 +1,9 @@ +.git +.gradle +build +run + +*.md +*.json +gradlew.bat +template.xsd diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..91ea741 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +build +.gradle diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..30ae425 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,10 @@ +FROM gradle:jdk16 AS compiler +WORKDIR /home/gradle/project +COPY build.gradle gradlew settings.gradle ./ +COPY src src +RUN gradle shadowJar + +FROM adoptopenjdk:16-jre-hotspot AS runner +WORKDIR /app +COPY --from=compiler /home/gradle/project/build/**/*.jar proximity.jar +CMD ["java", "-jar", "proximity.jar"] From 6ff92b810adbc1c4f72981226ce55a6f7b7ff839 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 29 Sep 2021 16:24:52 +0200 Subject: [PATCH 02/18] Various improvements to Docker setup --- .dockerignore | 2 ++ .gitignore | 8 ++++++++ Dockerfile | 11 +++++++---- README.md | 14 ++++++++++++++ 4 files changed, 31 insertions(+), 4 deletions(-) diff --git a/.dockerignore b/.dockerignore index 811eada..2922479 100644 --- a/.dockerignore +++ b/.dockerignore @@ -5,5 +5,7 @@ run *.md *.json +*.zip +*.txt gradlew.bat template.xsd diff --git a/.gitignore b/.gitignore index 91ea741..f97c5ed 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,10 @@ build +gradle +images +templates .gradle + + +*.swp +*.txt +*.zip diff --git a/Dockerfile b/Dockerfile index 30ae425..bbd30c2 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,10 +1,13 @@ FROM gradle:jdk16 AS compiler -WORKDIR /home/gradle/project +WORKDIR /home/gradle + COPY build.gradle gradlew settings.gradle ./ COPY src src -RUN gradle shadowJar +RUN gradle -i --no-daemon shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app -COPY --from=compiler /home/gradle/project/build/**/*.jar proximity.jar -CMD ["java", "-jar", "proximity.jar"] +COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar + +CMD ["--cards=cards.txt", "--template=template.zip"] +ENTRYPOINT ["java", "-jar", "proximity.jar"] diff --git a/README.md b/README.md index 9b9616b..3cbe225 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,16 @@ # Proximity A tool to assemble Magic: The Gathering proxies from a set of template images + +# Docker support +To run this tool in docker, clone the repository, then run: +``` +docker build proximity:latest . +``` + +Once it's done building, run the following: +``` +docker run -v $PWD/_CARDS_:/app/cards.txt -v $PWD/_TEMPLATE_.zip:/app/templates/template.zip -v $(PWD)/images:/app/images proximity:latest +``` + +Where `_CARDS_` is the name of the file containing your cards list, and `_TEMPLATE_` is the name of your template zip file. +Output of proximity will end up in a folder named `images`. From 4bac9cbef447e491eb0e5b47aa36fddfd8daa8d3 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 29 Sep 2021 16:35:13 +0200 Subject: [PATCH 03/18] Fix ignore files a bit --- .dockerignore | 2 ++ .gitignore | 4 +--- Dockerfile | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.dockerignore b/.dockerignore index 2922479..a1e200b 100644 --- a/.dockerignore +++ b/.dockerignore @@ -2,6 +2,8 @@ .gradle build run +templates +images *.md *.json diff --git a/.gitignore b/.gitignore index f97c5ed..1a2392a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,7 @@ +.gradle build -gradle images templates -.gradle - *.swp *.txt diff --git a/Dockerfile b/Dockerfile index bbd30c2..f700371 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,9 +1,9 @@ FROM gradle:jdk16 AS compiler WORKDIR /home/gradle -COPY build.gradle gradlew settings.gradle ./ +COPY gradle build.gradle gradlew settings.gradle ./ COPY src src -RUN gradle -i --no-daemon shadowJar +RUN gradle --no-daemon shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app From c3ad23fcb2759ae8002bb3e72ae108a0a145d767 Mon Sep 17 00:00:00 2001 From: gikkman Date: Thu, 30 Sep 2021 11:12:33 +0200 Subject: [PATCH 04/18] Add docker-compose support --- .gitignore | 2 +- README.md | 11 ++++++++--- Dockerfile => docker/Dockerfile | 5 +++-- docker/docker-compose.yml | 18 ++++++++++++++++++ docker/entrypoint.sh | 10 ++++++++++ templates/.gitkeep | 0 6 files changed, 40 insertions(+), 6 deletions(-) rename Dockerfile => docker/Dockerfile (62%) create mode 100644 docker/docker-compose.yml create mode 100755 docker/entrypoint.sh create mode 100644 templates/.gitkeep diff --git a/.gitignore b/.gitignore index 1a2392a..1114fc1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ .gradle build images -templates +templates/* *.swp *.txt diff --git a/README.md b/README.md index 3cbe225..299995a 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,18 @@ A tool to assemble Magic: The Gathering proxies from a set of template images # Docker support To run this tool in docker, clone the repository, then run: ``` -docker build proximity:latest . +docker build -t proximity:latest -f docker/Dockerfile . ``` Once it's done building, run the following: ``` -docker run -v $PWD/_CARDS_:/app/cards.txt -v $PWD/_TEMPLATE_.zip:/app/templates/template.zip -v $(PWD)/images:/app/images proximity:latest +docker run -v $PWD/_CARDS_:/app/cards.txt -v $PWD/templates/_TEMPLATE_.zip:/app/templates/template.zip -v $(PWD)/images:/app/images proximity:latest ``` -Where `_CARDS_` is the name of the file containing your cards list, and `_TEMPLATE_` is the name of your template zip file. +Where `_CARDS_` is the name of the file containing your cards list, and `_TEMPLATE_` is the name of your template zip file. +This assumes that your `_CARDS_` file resides in the root of the `Proximity` project, and your `_TEMPLATE_` file resides in +the `templates` folder. Output of proximity will end up in a folder named `images`. + +If you prefer `docker-compose`, you can run `docker-compose up` from the `docker` folder. If you do, you might need to modify the `environment` variables of the +`docker-compose.yml` file to fit the name of your cards file, and your template file. diff --git a/Dockerfile b/docker/Dockerfile similarity index 62% rename from Dockerfile rename to docker/Dockerfile index f700371..099c8a5 100644 --- a/Dockerfile +++ b/docker/Dockerfile @@ -7,7 +7,8 @@ RUN gradle --no-daemon shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app +COPY ./docker/entrypoint.sh ./entrypoint.sh COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar -CMD ["--cards=cards.txt", "--template=template.zip"] -ENTRYPOINT ["java", "-jar", "proximity.jar"] +CMD ["java", "-jar", "proximity.jar", "--cards=cards.txt", "--template=template.zip"] +ENTRYPOINT ["./entrypoint.sh"] diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml new file mode 100644 index 0000000..562c083 --- /dev/null +++ b/docker/docker-compose.yml @@ -0,0 +1,18 @@ +version: '3' +services: + proximity: + build: + context: ../ + dockerfile: ./Dockerfile + image: proximity:latest + volumes: + - ../cards.txt:/app/cards.txt + - ../templates:/app/templates + - ../images:/app/images + command: + - sh + - -c + - java -jar proximity.jar --cards=$$CARDS --template=$$TEMPLATE + environment: + CARDS: cards.txt + TEMPLATE: chilli.zip \ No newline at end of file diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100755 index 0000000..a2e181d --- /dev/null +++ b/docker/entrypoint.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -e + +# if first arg is an option, run proximity with those options +if [ "${1#-}" != "$1" ]; then + java -jar proximity.jar "$@" +else + exec "$@" +fi + diff --git a/templates/.gitkeep b/templates/.gitkeep new file mode 100644 index 0000000..e69de29 From eac1c338d7e46d8ef30eb8860c045631143786a6 Mon Sep 17 00:00:00 2001 From: gikkman Date: Thu, 30 Sep 2021 11:51:59 +0200 Subject: [PATCH 05/18] Simplify Dockerfile slightly --- docker/Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index 099c8a5..0a0b09d 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -10,5 +10,5 @@ WORKDIR /app COPY ./docker/entrypoint.sh ./entrypoint.sh COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar -CMD ["java", "-jar", "proximity.jar", "--cards=cards.txt", "--template=template.zip"] +CMD ["--cards=cards.txt", "--template=template.zip"] ENTRYPOINT ["./entrypoint.sh"] From 92862b13d90f9112e62dcb54c752fa2bb8a4066a Mon Sep 17 00:00:00 2001 From: gikkman Date: Thu, 30 Sep 2021 11:55:52 +0200 Subject: [PATCH 06/18] Clear up README on docker a bit --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 299995a..0ed4f3a 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,9 @@ docker run -v $PWD/_CARDS_:/app/cards.txt -v $PWD/templates/_TEMPLATE_.zip:/app/ ``` Where `_CARDS_` is the name of the file containing your cards list, and `_TEMPLATE_` is the name of your template zip file. -This assumes that your `_CARDS_` file resides in the root of the `Proximity` project, and your `_TEMPLATE_` file resides in -the `templates` folder. -Output of proximity will end up in a folder named `images`. +This assumes that your _CARDS_ file resides in the root of the Proximity project, and your _TEMPLATE_ file resides in +the templates folder. +Output of proximity will end up in a folder named images. -If you prefer `docker-compose`, you can run `docker-compose up` from the `docker` folder. If you do, you might need to modify the `environment` variables of the -`docker-compose.yml` file to fit the name of your cards file, and your template file. +If you prefer docker-compose, you can run `docker-compose up` from the docker folder. If you do, you might need to modify the environment variables of the +docker-compose.yml file to fit the name of your cards file, and your template file. From 103c71597d40db4087a7948acb4606f188d7bf3f Mon Sep 17 00:00:00 2001 From: gikkman Date: Tue, 5 Oct 2021 17:32:38 +0200 Subject: [PATCH 07/18] Polish the docker setup I hope this setup is clearer, and explains a bit more into detail how to use the docker setup, and what motivates the design choices made. I've also tried to rectify the problem with what user owns the generated files. I'll need someone with an true linux environment (and not just a VM) to try it out in practise though --- .dockerignore | 7 ++-- README.md | 17 ++++---- art/.gitkeep | 0 cards.txt | 3 ++ docker/Dockerfile | 13 ++++-- docker/README.md | 84 +++++++++++++++++++++++++++++++++++++++ docker/docker-compose.yml | 18 ++++----- 7 files changed, 117 insertions(+), 25 deletions(-) create mode 100644 art/.gitkeep create mode 100644 cards.txt create mode 100644 docker/README.md diff --git a/.dockerignore b/.dockerignore index a1e200b..19852da 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,13 +1,12 @@ .git .gradle +.idea +art build +images run templates -images -*.md -*.json *.zip -*.txt gradlew.bat template.xsd diff --git a/README.md b/README.md index 0ed4f3a..544269d 100644 --- a/README.md +++ b/README.md @@ -2,20 +2,19 @@ A tool to assemble Magic: The Gathering proxies from a set of template images # Docker support -To run this tool in docker, clone the repository, then run: +To run this tool in docker, clone the repository, then, depending on platform, run the below command from the root of the project: ``` +-- LINUX +docker build -t proximity:latest -f docker/Dockerfile --build-arg GROUP_ID=$(id -g) --build-arg USER_ID=$(id -u) . + +-- WINDOWS or MAC docker build -t proximity:latest -f docker/Dockerfile . ``` -Once it's done building, run the following: +Once it's done building, run the command below. Output of proximity will end up in a folder named `images`. ``` -docker run -v $PWD/_CARDS_:/app/cards.txt -v $PWD/templates/_TEMPLATE_.zip:/app/templates/template.zip -v $(PWD)/images:/app/images proximity:latest +docker-compose -f docker/docker-compose.yml up ``` -Where `_CARDS_` is the name of the file containing your cards list, and `_TEMPLATE_` is the name of your template zip file. -This assumes that your _CARDS_ file resides in the root of the Proximity project, and your _TEMPLATE_ file resides in -the templates folder. -Output of proximity will end up in a folder named images. -If you prefer docker-compose, you can run `docker-compose up` from the docker folder. If you do, you might need to modify the environment variables of the -docker-compose.yml file to fit the name of your cards file, and your template file. +For more details on the docker setup, and how to tweek if further, please see the [docker readme](./docker/README.md) diff --git a/art/.gitkeep b/art/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/cards.txt b/cards.txt new file mode 100644 index 0000000..4dfcc32 --- /dev/null +++ b/cards.txt @@ -0,0 +1,3 @@ +1x Peek +1x Shock +1x Murder \ No newline at end of file diff --git a/docker/Dockerfile b/docker/Dockerfile index 0a0b09d..e5e7d47 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -7,8 +7,15 @@ RUN gradle --no-daemon shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app -COPY ./docker/entrypoint.sh ./entrypoint.sh -COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar -CMD ["--cards=cards.txt", "--template=template.zip"] +ARG USER_ID=1000 +ARG GROUP_ID=1000 +RUN addgroup --gid $GROUP_ID user +RUN adduser --disabled-password --gecos '' --uid $USER_ID --gid $GROUP_ID user +USER user + +COPY --chown=user --from=compiler /home/gradle/build/**/*.jar proximity.jar +COPY --chown=user docker/entrypoint.sh entrypoint.sh + +CMD ["--template=normal", "--cards=cardslist"] ENTRYPOINT ["./entrypoint.sh"] diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..2ca84e6 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,84 @@ +# Building the docker image +To build the docker image, depending on platform, run the below command from the root of the project: +``` +-- LINUX +docker build -t proximity:latest -f docker/Dockerfile --build-arg GROUP_ID=$(id -g) --build-arg USER_ID=$(id -u) . + +-- WINDOWS or MAC +docker build -t proximity:latest -f docker/Dockerfile . +``` + +# Running the docker image via compose +Once it's done building, run the command below from the root of the project. Output of proximity will +end up in a folder named `images`. +``` +docker-compose -f docker/docker-compose.yml up +``` + +# Tweeking docker setup +This section aims to explain the different docker settings you can tinker with, as well as motivating some of +the design choices that's been made with regards to the docker files. + +## Docker compose settings +The `docker-compose.yml` file controls what's going on once we run Proximity inside the docker container. +There are a couple of defaults set to give a smooth user experience firs time around: We +automatically mount and use the `cards.txt` file as the cardslist we'll generate, and we automatically +mount the `run/templates` folder, and use the `normal` template for card generation. Lastly, we mount +the `images` folder as output target for the Proximity process. + +### Change the cards list +The simplest solution is to just edit the content of the existing `cards.txt` file to whatever you want. +If that for some reason isn't an option, and you would like to use another file for cards, replace the path +of the file to mount as cardslist (What's left of the `:` in Volume 1. The path is relative to the +docker-compose.yml file). + +### Change the template +If you would like to use another template, the easiest solution is to place it in the `run/tempaltes` +folder, and change `normal` in the `--template=normal` part of the run command to the name of the +new template folder (or the zip file, if you opt for using a zip). + +### Change the output folder +If you would like to change the output folder, replace the path of the mounted output folder. +(What's left of the `:` in Volume 1. The path is relative to the docker-compose.yml file). + +### Change command-line flags +If you want to add additional command line flags to pass to Proximity, the easiest is to just add them +at the end of the `run` command. A complete list of command-line flags that can be passed can be found +on the [wiki](https://github.com/Haven-King/Proximity/wiki). + +## Running without compose +If you for some reason want to run the docker image without using compose, you will need to mount the +various volumes manually, and pass the appropriate CLI flags. By default, the image is design to pass +the cli flags `--template=normal --cards=cardslist`, and uses `/app` as working directory. So the most +convenient is to mount your list of cards at `/app/cardslist` and your template at `/app/templates/normal`. +Then, you will also need to mount an output folder, to be able to extract the generated cards. Proximity +outputs cards in a folder called `images`, so you'll need to mount a folder at `/app/images` to be able +to extract them. + +An example command to achieve all this would be the following. This command will run Proximity with the +all the default flags. +``` +docker run -v $PWD/cards.txt:/app/cardslist -v $PWD/run/template/normal:/app/templates/normal -v $PWD/images:/app/images proximity:latest +``` + +If you want to provide your own set of flags, you will need to manually include the `--cards` and the +`--template` flags in addition to whatever flags you wish. A + +## File owners on Linus (aka. "Why --build-args on Linux") +Files generated inside a docker container is owned by whatever process is executing the docker process. On +Mac and Windows, the docker process is run by the current user process, so files generated by the docker +process is owned by the user. But on Linux, the docker process is normally run as the `root` user. This +is normally not a problem, since docker isolates its file system inside the container. Proximity however +generates files that we want to access from outside the container (the output images), and thus, we mount +a directory to gain access to those files once they are generated. But since the files were generated by +the root user on Linux, normal users can't access these files. + +Thus, we need a way for the docker process to generate files that can be accessed by the host user. There +are two ways you can go about it: force-set the user running the container command (i.e. the `-u` flag) or +creating a user when building the docker image with matching user- and group-id, and then setting that user +as the default user of the image. We've opted for the later, because then you are only required to pass the +user- and group-id when you build the image, and not everytime you run the image. The hope is that ut makes +for a slightly more convenient user experience. The drawback of this approach however is that the built +docker image cannot be shared between users, as the built image is locked to the user- and group-id of +whoever built the image. If we descide to one day publish pre-built docker images, we would need to revisit +this design descision and instead set the user on each run command. diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 562c083..ebd3820 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -4,15 +4,15 @@ services: build: context: ../ dockerfile: ./Dockerfile + args: + - USER_ID: ${USER_ID} + - GROUP_ID: ${GROUP_ID} image: proximity:latest volumes: - - ../cards.txt:/app/cards.txt - - ../templates:/app/templates - - ../images:/app/images + - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as decklist + - ../run/templates:/app/templates # Volume 2 - Mounts templates from run/templates (i.e. normal and classic) + - ../images:/app/images # Volume 3 - Mounts the output folder command: - - sh - - -c - - java -jar proximity.jar --cards=$$CARDS --template=$$TEMPLATE - environment: - CARDS: cards.txt - TEMPLATE: chilli.zip \ No newline at end of file + - sh + - -c + - java -jar proximity.jar --cards=cardslist --template=normal --use_official_art=true \ No newline at end of file From 028f97c5352364b172ff2b08a7af205aa4dab835 Mon Sep 17 00:00:00 2001 From: gikkman Date: Tue, 5 Oct 2021 17:34:24 +0200 Subject: [PATCH 08/18] Remove gitkeep from templates No need to keep this folder around since we can mount the templates from run/templates --- templates/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 templates/.gitkeep diff --git a/templates/.gitkeep b/templates/.gitkeep deleted file mode 100644 index e69de29..0000000 From ec83ca49cf98051197f73f8966655171d13dff89 Mon Sep 17 00:00:00 2001 From: gikkman Date: Tue, 5 Oct 2021 17:35:08 +0200 Subject: [PATCH 09/18] Add blank space at end of compose file --- docker/docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index ebd3820..cc0a9b3 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -15,4 +15,4 @@ services: command: - sh - -c - - java -jar proximity.jar --cards=cardslist --template=normal --use_official_art=true \ No newline at end of file + - java -jar proximity.jar --cards=cardslist --template=normal --use_official_art=true From a69c50cba5cb67f8af2e27dc9b555455ed363920 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 6 Oct 2021 12:08:04 +0200 Subject: [PATCH 10/18] Fix formatting of the compose file --- docker/docker-compose.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index cc0a9b3..02bd173 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -5,8 +5,8 @@ services: context: ../ dockerfile: ./Dockerfile args: - - USER_ID: ${USER_ID} - - GROUP_ID: ${GROUP_ID} + USER_ID: ${USER_ID:-1000} + GROUP_ID: ${GROUP_ID:-1000} image: proximity:latest volumes: - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as decklist From e16ebbd482f698c1c330650f829d973beb938b91 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 6 Oct 2021 12:14:14 +0200 Subject: [PATCH 11/18] Clarify a command on docker README --- docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/README.md b/docker/README.md index 2ca84e6..c89c37e 100644 --- a/docker/README.md +++ b/docker/README.md @@ -56,7 +56,7 @@ outputs cards in a folder called `images`, so you'll need to mount a folder at ` to extract them. An example command to achieve all this would be the following. This command will run Proximity with the -all the default flags. +all the default flags (run it from the root of this project). ``` docker run -v $PWD/cards.txt:/app/cardslist -v $PWD/run/template/normal:/app/templates/normal -v $PWD/images:/app/images proximity:latest ``` From 31e389fd4f5e85f71207e29f96f9e64763b8dfd4 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 6 Oct 2021 15:07:34 +0200 Subject: [PATCH 12/18] Fix docker-compose ref and docker user --- README.md | 10 ++-------- docker/Dockerfile | 10 ++-------- docker/README.md | 15 ++++----------- docker/docker-compose.yml | 8 +++----- 4 files changed, 11 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 544269d..eb78119 100644 --- a/README.md +++ b/README.md @@ -4,17 +4,11 @@ A tool to assemble Magic: The Gathering proxies from a set of template images # Docker support To run this tool in docker, clone the repository, then, depending on platform, run the below command from the root of the project: ``` --- LINUX -docker build -t proximity:latest -f docker/Dockerfile --build-arg GROUP_ID=$(id -g) --build-arg USER_ID=$(id -u) . +--LINUX +GROUP_ID=$(id -g) USER_ID=$(id -u) docker-compose -f docker/docker-compose.yml up -- WINDOWS or MAC -docker build -t proximity:latest -f docker/Dockerfile . -``` - -Once it's done building, run the command below. Output of proximity will end up in a folder named `images`. -``` docker-compose -f docker/docker-compose.yml up ``` - For more details on the docker setup, and how to tweek if further, please see the [docker readme](./docker/README.md) diff --git a/docker/Dockerfile b/docker/Dockerfile index e5e7d47..11776a5 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -8,14 +8,8 @@ RUN gradle --no-daemon shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app -ARG USER_ID=1000 -ARG GROUP_ID=1000 -RUN addgroup --gid $GROUP_ID user -RUN adduser --disabled-password --gecos '' --uid $USER_ID --gid $GROUP_ID user -USER user - -COPY --chown=user --from=compiler /home/gradle/build/**/*.jar proximity.jar -COPY --chown=user docker/entrypoint.sh entrypoint.sh +COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar +COPY docker/entrypoint.sh entrypoint.sh CMD ["--template=normal", "--cards=cardslist"] ENTRYPOINT ["./entrypoint.sh"] diff --git a/docker/README.md b/docker/README.md index c89c37e..3236c6b 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,17 +1,10 @@ -# Building the docker image -To build the docker image, depending on platform, run the below command from the root of the project: +# Running the docker image via compose +To run this tool in docker, clone the repository, then, depending on platform, run the below command from the root of the project: ``` --- LINUX -docker build -t proximity:latest -f docker/Dockerfile --build-arg GROUP_ID=$(id -g) --build-arg USER_ID=$(id -u) . +--LINUX +GROUP_ID=$(id -g) USER_ID=$(id -u) docker-compose -f docker/docker-compose.yml up -- WINDOWS or MAC -docker build -t proximity:latest -f docker/Dockerfile . -``` - -# Running the docker image via compose -Once it's done building, run the command below from the root of the project. Output of proximity will -end up in a folder named `images`. -``` docker-compose -f docker/docker-compose.yml up ``` diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 02bd173..49b9746 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -3,13 +3,11 @@ services: proximity: build: context: ../ - dockerfile: ./Dockerfile - args: - USER_ID: ${USER_ID:-1000} - GROUP_ID: ${GROUP_ID:-1000} + dockerfile: ./docker/Dockerfile + user: ${USER_ID:-0}:${GROUP_ID:-0} image: proximity:latest volumes: - - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as decklist + - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as cardslist - ../run/templates:/app/templates # Volume 2 - Mounts templates from run/templates (i.e. normal and classic) - ../images:/app/images # Volume 3 - Mounts the output folder command: From c0c8f6822b91c6e7ec442b6d413bc17e2ec475b2 Mon Sep 17 00:00:00 2001 From: gikkman Date: Wed, 6 Oct 2021 15:25:41 +0200 Subject: [PATCH 13/18] Update docker readme to reflect new user approach --- docker/README.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docker/README.md b/docker/README.md index 3236c6b..af97c72 100644 --- a/docker/README.md +++ b/docker/README.md @@ -67,11 +67,8 @@ a directory to gain access to those files once they are generated. But since the the root user on Linux, normal users can't access these files. Thus, we need a way for the docker process to generate files that can be accessed by the host user. There -are two ways you can go about it: force-set the user running the container command (i.e. the `-u` flag) or +are two ways you can go about it: set the user running the container command (i.e. the `-u` flag or `user` in compose) or creating a user when building the docker image with matching user- and group-id, and then setting that user -as the default user of the image. We've opted for the later, because then you are only required to pass the -user- and group-id when you build the image, and not everytime you run the image. The hope is that ut makes -for a slightly more convenient user experience. The drawback of this approach however is that the built -docker image cannot be shared between users, as the built image is locked to the user- and group-id of -whoever built the image. If we descide to one day publish pre-built docker images, we would need to revisit -this design descision and instead set the user on each run command. +as the default user of the image. We first tried with the later approach, but abandoned it in favor of the first +because of the risks of building an incorrect image and having to force-rebuild it to fix the issue. Now, worst +case is that linux users generates a bunch of files owned by root. \ No newline at end of file From 404bff4948a1d6a24713a5049d1c0a271e267e8d Mon Sep 17 00:00:00 2001 From: gikkman Date: Sat, 9 Oct 2021 11:38:37 +0200 Subject: [PATCH 14/18] Update docker setup based on comments After some input from others involved in this PR I descided it was probably best to leave the file owner problem as an optional solution, instead of forcing it upon users. I also clarified the docker readme even more, to hopefully explain why its designed as it is --- README.md | 10 ++---- docker/Dockerfile | 3 +- docker/README.md | 67 +++++++++++++++++++++++++-------------- docker/docker-compose.yml | 9 +++--- docker/entrypoint.sh | 13 ++++++-- 5 files changed, 62 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index eb78119..40fe5da 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,9 @@ A tool to assemble Magic: The Gathering proxies from a set of template images # Docker support -To run this tool in docker, clone the repository, then, depending on platform, run the below command from the root of the project: +To run this tool in docker, clone the repository, then run the below command from the root of the project. +If you are on Linux, make sure the read the segment on file ownership in the [docker readme](./docker/README.md). ``` ---LINUX -GROUP_ID=$(id -g) USER_ID=$(id -u) docker-compose -f docker/docker-compose.yml up - --- WINDOWS or MAC docker-compose -f docker/docker-compose.yml up ``` - -For more details on the docker setup, and how to tweek if further, please see the [docker readme](./docker/README.md) +For more details on the docker setup, and how to tweek if further, please see the [docker readme](./docker/README.md). diff --git a/docker/Dockerfile b/docker/Dockerfile index 11776a5..4421faf 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -3,7 +3,7 @@ WORKDIR /home/gradle COPY gradle build.gradle gradlew settings.gradle ./ COPY src src -RUN gradle --no-daemon shadowJar +RUN gradle shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app @@ -11,5 +11,4 @@ WORKDIR /app COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar COPY docker/entrypoint.sh entrypoint.sh -CMD ["--template=normal", "--cards=cardslist"] ENTRYPOINT ["./entrypoint.sh"] diff --git a/docker/README.md b/docker/README.md index af97c72..3064210 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,12 +1,14 @@ # Running the docker image via compose To run this tool in docker, clone the repository, then, depending on platform, run the below command from the root of the project: ``` ---LINUX -GROUP_ID=$(id -g) USER_ID=$(id -u) docker-compose -f docker/docker-compose.yml up - --- WINDOWS or MAC docker-compose -f docker/docker-compose.yml up ``` +Remember that once a docker image is built, it will be reused for all subsequent runs unless a new image +is created that replaces it. To rebuild the image (if you pull new code changes, for example), append +the `--build` flag to the command, like this: +``` +docker-compose -f docker/docker-compose.yml up --build +``` # Tweeking docker setup This section aims to explain the different docker settings you can tinker with, as well as motivating some of @@ -26,7 +28,7 @@ of the file to mount as cardslist (What's left of the `:` in Volume 1. The path docker-compose.yml file). ### Change the template -If you would like to use another template, the easiest solution is to place it in the `run/tempaltes` +If you would like to use another template, the easiest solution is to place it in the `run/templates` folder, and change `normal` in the `--template=normal` part of the run command to the name of the new template folder (or the zip file, if you opt for using a zip). @@ -36,39 +38,56 @@ If you would like to change the output folder, replace the path of the mounted o ### Change command-line flags If you want to add additional command line flags to pass to Proximity, the easiest is to just add them -at the end of the `run` command. A complete list of command-line flags that can be passed can be found +at the end of the `command` section. A complete list of command-line flags that can be passed can be found on the [wiki](https://github.com/Haven-King/Proximity/wiki). ## Running without compose If you for some reason want to run the docker image without using compose, you will need to mount the -various volumes manually, and pass the appropriate CLI flags. By default, the image is design to pass -the cli flags `--template=normal --cards=cardslist`, and uses `/app` as working directory. So the most -convenient is to mount your list of cards at `/app/cardslist` and your template at `/app/templates/normal`. -Then, you will also need to mount an output folder, to be able to extract the generated cards. Proximity -outputs cards in a folder called `images`, so you'll need to mount a folder at `/app/images` to be able -to extract them. +various volumes manually, and pass the appropriate CLI flags. By default, the image is design to use `/app` + as working directory. So the most convenient is to mount your list of cards at `/app/cardslist` and +your template at `/app/templates/normal`. Then, you will also need to mount an output folder, to be +able to extract the generated cards. Proximity outputs cards in a folder called `images`, so you'll +need to mount a folder at `/app/images` to be able to extract them. An example command to achieve all this would be the following. This command will run Proximity with the -all the default flags (run it from the root of this project). +required mounts, and will include the `--cards` and `--template` flag. ``` -docker run -v $PWD/cards.txt:/app/cardslist -v $PWD/run/template/normal:/app/templates/normal -v $PWD/images:/app/images proximity:latest +docker run \ + -v $PWD/cards.txt:/app/cardslist \ + -v $PWD/run/templates:/app/templates \ + -v $PWD/images:/app/images \ + proximity:latest \ + --cards=cardslist --template=normal ``` -If you want to provide your own set of flags, you will need to manually include the `--cards` and the -`--template` flags in addition to whatever flags you wish. A - -## File owners on Linus (aka. "Why --build-args on Linux") +## File owners on Linus Files generated inside a docker container is owned by whatever process is executing the docker process. On Mac and Windows, the docker process is run by the current user process, so files generated by the docker process is owned by the user. But on Linux, the docker process is normally run as the `root` user. This is normally not a problem, since docker isolates its file system inside the container. Proximity however generates files that we want to access from outside the container (the output images), and thus, we mount a directory to gain access to those files once they are generated. But since the files were generated by -the root user on Linux, normal users can't access these files. +the root user on Linux, normal users can't access these files. + +For some distros of Linux, you can grant access to files generated by the docker process by adding your +user to the `docker` group (see for example [Arch's instructions](https://wiki.archlinux.org/title/Docker#Installation)). +This might not always be an option for you though: being part of the docker group easilly gives the user +priveledge access to the system via `docker run --privileged`. Thus, we need a way for the docker process to generate files that can be accessed by the host user. There -are two ways you can go about it: set the user running the container command (i.e. the `-u` flag or `user` in compose) or -creating a user when building the docker image with matching user- and group-id, and then setting that user -as the default user of the image. We first tried with the later approach, but abandoned it in favor of the first -because of the risks of building an incorrect image and having to force-rebuild it to fix the issue. Now, worst -case is that linux users generates a bunch of files owned by root. \ No newline at end of file +are a few ways you can go about it, and the most common way is to set tell docker what user id and group id +to execute the container as (i.e. the `-u` flag or `user` in compose). But setting the user can have +some odd side effects on programs running in a container, because the assigned user doesn't really +exist and thus doesn't have what a program might assume a user has (for example, a home directory). +It also isn't easy to shop those settings pre-configured in a compose file, + +Instead, we went with an approach where users may supply their user id and group id as environment +variables when executing the docker compose command. If the `GROUP_ID` and `USER_ID` env vars are +set when composer runs, those values are passed to the container. The entrypoint script will then +see these values, and run `chown -R` for those values on the generated output. + +### TL:DR +Run the following on a Linux machine if you experience problems with file ownership: +```` +GROUP_ID=$(id -g) USER_ID=$(id -u) docker-compose -f docker/docker-compose.yml up +``` diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 49b9746..df46b8f 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -4,13 +4,12 @@ services: build: context: ../ dockerfile: ./docker/Dockerfile - user: ${USER_ID:-0}:${GROUP_ID:-0} + environment: + USER_ID: ${USER_ID:-0} + GROUP_ID: ${GROUP_ID:-0} image: proximity:latest volumes: - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as cardslist - ../run/templates:/app/templates # Volume 2 - Mounts templates from run/templates (i.e. normal and classic) - ../images:/app/images # Volume 3 - Mounts the output folder - command: - - sh - - -c - - java -jar proximity.jar --cards=cardslist --template=normal --use_official_art=true + command: --cards=cardslist --template=normal --use_official_art=true diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh index a2e181d..67e7b40 100755 --- a/docker/entrypoint.sh +++ b/docker/entrypoint.sh @@ -1,10 +1,19 @@ #!/bin/sh set -e -# if first arg is an option, run proximity with those options -if [ "${1#-}" != "$1" ]; then +# if the first arg is an option, pass all args to proximity +# else just exec whatever was supplied +if [ -z "$1" ]; then + echo "Please either supply options for Proximity, or a command to execute" +elif [ "${1#-}" != "$1" ]; then java -jar proximity.jar "$@" else exec "$@" fi +# if the USER_ID and GROUP_ID env vars are not 0, and the /app/images +# directory exists, chown /app/images to user USER_ID:GROUP_ID +if [ "$USER_ID" -ne "0" -a "$GROUP_ID" -ne "0" -a -d "/app/images" ]; then + echo "Running: chown -R $USER_ID:$GROUP_ID /app/images" + chown -R $USER_ID:$GROUP_ID /app/images +fi \ No newline at end of file From d7bbb8781d5ebea5823a66095bbbcd3aee520cab Mon Sep 17 00:00:00 2001 From: gikkman Date: Sat, 9 Oct 2021 11:45:22 +0200 Subject: [PATCH 15/18] Update gitignore --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 1114fc1..357fd56 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ .gradle build images -templates/* +templates +art *.swp *.txt From e4bc038ab01b59fabf43f88e260e5ba868bcf69e Mon Sep 17 00:00:00 2001 From: gikkman Date: Sat, 9 Oct 2021 11:48:00 +0200 Subject: [PATCH 16/18] Fix a comment typo --- docker/entrypoint.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh index 67e7b40..ac71c04 100755 --- a/docker/entrypoint.sh +++ b/docker/entrypoint.sh @@ -11,9 +11,9 @@ else exec "$@" fi -# if the USER_ID and GROUP_ID env vars are not 0, and the /app/images +# if the USER_ID and GROUP_ID env vars are not 0, and the /app/images # directory exists, chown /app/images to user USER_ID:GROUP_ID if [ "$USER_ID" -ne "0" -a "$GROUP_ID" -ne "0" -a -d "/app/images" ]; then echo "Running: chown -R $USER_ID:$GROUP_ID /app/images" chown -R $USER_ID:$GROUP_ID /app/images -fi \ No newline at end of file +fi From 3f50055871f423a519bf38ef3ff823452f424a75 Mon Sep 17 00:00:00 2001 From: gikkman Date: Thu, 11 Nov 2021 11:19:04 +0100 Subject: [PATCH 17/18] Updates for 0.5.0 --- docker/Dockerfile | 2 +- docker/docker-compose.yml | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index 4421faf..2e85693 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -8,7 +8,7 @@ RUN gradle shadowJar FROM adoptopenjdk:16-jre-hotspot AS runner WORKDIR /app -COPY --from=compiler /home/gradle/build/**/*.jar proximity.jar +COPY --from=compiler /home/gradle/build/**/*all.jar proximity.jar COPY docker/entrypoint.sh entrypoint.sh ENTRYPOINT ["./entrypoint.sh"] diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index df46b8f..43d4dfb 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -9,7 +9,8 @@ services: GROUP_ID: ${GROUP_ID:-0} image: proximity:latest volumes: - - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as cardslist - - ../run/templates:/app/templates # Volume 2 - Mounts templates from run/templates (i.e. normal and classic) - - ../images:/app/images # Volume 3 - Mounts the output folder + - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as cardslist + - ../templates:/app/templates # Volume 2 - Mounts templates from run/templates (i.e. normal and classic) + - ../images:/app/images # Volume 3 - Mounts the output folder + - ../art:/app/art # Volume 4 - Mounts local art folder command: --cards=cardslist --template=normal --use_official_art=true From eab58f220b0fd1b3281bc4c4c7a24683049e5820 Mon Sep 17 00:00:00 2001 From: gikkman Date: Mon, 15 Nov 2021 09:07:31 +0100 Subject: [PATCH 18/18] Update readmes --- docker/README.md | 1 + docker/docker-compose.yml | 3 ++- templates/.gitkeep | 0 3 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 templates/.gitkeep diff --git a/docker/README.md b/docker/README.md index 3064210..d2e19cb 100644 --- a/docker/README.md +++ b/docker/README.md @@ -56,6 +56,7 @@ docker run \ -v $PWD/cards.txt:/app/cardslist \ -v $PWD/run/templates:/app/templates \ -v $PWD/images:/app/images \ + -v $PWD/art:/app/art \ proximity:latest \ --cards=cardslist --template=normal ``` diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml index 43d4dfb..ed34a49 100644 --- a/docker/docker-compose.yml +++ b/docker/docker-compose.yml @@ -7,10 +7,11 @@ services: environment: USER_ID: ${USER_ID:-0} GROUP_ID: ${GROUP_ID:-0} + TEMPLATE_NAME: ${TEMPLATE_NAME:-} image: proximity:latest volumes: - ../cards.txt:/app/cardslist # Volume 1 - Mounts the default 'cards.txt' as cardslist - ../templates:/app/templates # Volume 2 - Mounts templates from run/templates (i.e. normal and classic) - ../images:/app/images # Volume 3 - Mounts the output folder - ../art:/app/art # Volume 4 - Mounts local art folder - command: --cards=cardslist --template=normal --use_official_art=true + command: --cards=cardslist --template=$TEMPLATE_NAME --use_official_art=true diff --git a/templates/.gitkeep b/templates/.gitkeep new file mode 100644 index 0000000..e69de29