Simplify the Docker setup

[PhilippMatthes]

@felix-kaestner I might have a possibility to further advance this – including a simultaneous possibility to simplify the Docker setup. The core idea of this project was to not have to install Latex locally on a machine, and to automatically publish the build theses to the release section on GitHub.

However, the current setup still has some remaining problems such as #7 – which originates in a too complex build system. As an entrypoint to this discussion: how about we condensate the build process to using the following command in a shell wrapper?

#!/bin/bash

docker run --rm \
    -v $PWD:/thesis\
    --platform linux/amd64 \
    kaestner/latex \
    bash -c "cd /thesis && $@"

Note that the --platform linux/amd64 may be needed for the image to work on M1 machines ;)

As such, the shell wrapper would mount a Docker container to the current workdir to build the thesis with ./wrapper latexmk thesis. This makes the usage of a complicated Makefile (like we currently do) unnecessary and gives much more flexibility as to which commands can be executed by the Docker container. Additionally, latex can make use of the mounted build files to reduce the build time drastically.

Let me know what you think of this @felix-kaestner!

[felix-kaestner]

@PhilippMatthes I don't think the build system is too complex. I would like to point out a few things.

1. The shell wrapper you provided is completly redundant because that is exactly what you do by executing

   $ make shell
   

   see https://github.com/PhilippMatthes/better-tudscr/blob/master/Makefile#L15

   That's the reason the shell command is included in the Makefile. No need for a shell wrapper, which in your case is directly linked to bash (other shell alternatives may be used) and may need Git-Bash or else on Windows.

2. The reason you have to use --platform linux/amd64 is that my latex image is only build for that target platform, which I can look into in the following days, which I think should be possible since GitHub Actions already supports MacOS runners, so I could build the docker image for multiple platforms in my CI-Pipeline. Maybe you could create a Issue for this and I would be happy to support multiple platforms.

3. I think the remaining problems from Docker container is draining storage after an environment-dependent number of runs #7 can be fixed by deleting the image which is used for the build process afterwards. I would look into this as well.

[PhilippMatthes]

@felix-kaestner thanks for your feedback, let me approach some of the considerations that you made. One of the main problems of the current setup is that the auxiliary files that are generated by LaTeX during the build are kept within the container that is used a single time (and not thrown away, hence causing #7). However, LaTeX can use the generated auxiliary files to perform subsequent builds much faster. This is especially a problem for bigger theses, where the build can take up to 2 minutes or more. My shell wrapper (which could presumably also use /bin/sh) would use a filesystem mount to mitigate those two problems. I could see the argument that the Docker container is in this case only used to carry the necessary LaTeX distribution and not the build data itself. However another advantage of using such a shell wrapper over the Makefile would be to simplify the usage of the containerized build in general. Instead of having to lookup which command does which thing in the Makefile, executing make shell and latexmk ..., users can use the multi-purpose shell wrapper to execute any command they are used to from using latexmk just by prepending the ./wrapped command. #7 could be closed as well without further investigation.

[felix-kaestner]

@PhilippMatthes I get your point, but what is the benefit from using a custom shell wrapper and calling ./wrapper latexmk thesis instead of make shell and then latexmk thesis? Either way, we could simply explain the procedure in the README and no one would have to look up anything. Explaining that a user can use a wrapper script and call ./wrapper latexmk .. is the same as explaining that a user can call make shell and then latexmk .... I would additionally see the benefit in the latter, as you would not have to create a new docker container on every latexmk invocation.
Additionally, #7 is another problem which occurs when calling make build and is not linked to the described workflow. My point is, that your proposed wrapper script is identical to the already present Makefile command. Either one could simply be explained and recommended for the process of writing and building multiple times in one session.

[PhilippMatthes]

@felix-kaestner thanks for the further points. Maybe the shell wrapper doesn't necessarily provide a better usability or understandability as initially proposed. I could argue that it is more swift than the Makefile option but I don't want to diverge into extensive opinionated discussions.

However I am still concerned about potential time gain when the auxiliary files could be included in subsequent builds. Additionally the use of a command as shown would make the Dockerfile redundant and therefore vastly simplify the build process. When testing today it didn't seem like the instantiation of a new container on each build added any humanly noticeable overhead. The improvement in time was obvious though.

[felix-kaestner]

Actually, I wouldn't agree that a shell wrapper is more swift than a Makefile, since Makefile’s are platform-agnostic and shell scripts tend to deviate depending on the platform.

The Dockerfile itself is redundant if you are having a user ID of 1000 (simply execute id -u to check) which is the default on Linux/MacOS systems. Therefore, the default user of the latex docker image has the same user ID as your local user, and you don't run into problems by mounting your current working directory into the container, since files created inside the container by the container user have correct permissions corresponding to your local user (in Linux terms the file is owned by 1000:1000). The Dockerfile and Makefile commands are simply there if the above is not the case and your local user does not have user ID 1000 (for whatever reason) and changes the container user's ID to the one of your local user (in order to make sure the above holds) before using the image.

Again, even if we skip the procedure explained above, the shell wrapper is the same as make shell, if you would like to simplify the process and assume every user of this project has a user ID of 1000 (which is actually very likely) or has enough knowledge of docker and Linux in order to fix the file permissions themselves than we can just change the DOCKER_IMAGE variable to kaestner/latex and remove the container command and USER_ID, USER_NAME and BASE_IMAGE variables from the Makefile and that would be it. Sorry if I repeat myself, but a ./containerized shell wrapper is the same as make shell. The latter is even better, since it spawns a new container and uses it until you are done (closing the shell), while the former will get complicated if you want to spawn a container and reuse it for subsequent runs.

[felix-kaestner]

Anyway, I will look into building the kaestner/latex docker image for the darwin/arm64 platform, so you can use it on a M1 MacBook without having to use --platform linux/amd64.

[felix-kaestner]

@PhilippMatthes the kaestner/latex docker image is now available for the arm64 platform. You should be able to use it, after you pulled the latest version from the docker registry with docker image pull kaestner/latex. 🚀

[PhilippMatthes]

@felix-kaestner I will close this issue since I am not sure how to proceed with the initial idea. Thanks for your feedback, though.