----------------------------------------------------------------------------------- COPYRIGHT INFORMATION ... HRConvert2, Copyright on 8/15/2026 by Justin Grimes, www.github.com/zelon88 LICENSE INFORMATION ... This project is protected by the GNU GPLv3 Open-Source license. https://www.gnu.org/licenses/gpl-3.0.html APPLICATION INFORMATION ... This application is designed to provide a web-interface for converting file formats on a server for users of any web browser without authentication. FILE INFORMATION ... v3.8.8. This file contains a walkthrough guide for building an HRConvert2 Docker Image from source. HARDWARE REQUIREMENTS ... This application requires at least a Raspberry Pi Model B+ or greater. This application will run on just about any x86 or x64 computer. DEPENDENCY REQUIREMENTS ... The authoritative list of dependencies is Resources/Engine/depends.php & Resources/Contract/depends.php, the Engine's half & the application's, & nothing else. Run php convertCore.php -v to see what this installation has. <3 Open-Source ----------------------------------------------------------------------------------- -----STEP 0 - ARE YOU IN THE RIGHT PLACE?----- In this step we will make sure your use case aligns with the purpose of this document. It is not necessary to perform the steps in this document to simply install and use the official HRConvert2 Docker Image. This document is intended to be used for development purposes by HRConvert2 maintainers. If you simply want to download and run HRConvert2, you can download the official pre-built docker image at the following URL. https://hub.docker.com/r/zelon88/hrconvert2 Usually people who want to run the official Docker image are people who; 1. Want to use HRConvert2 for personal, industrial, educational, non-profit, or commercial use on a small number of servers. 2. Want to run the most stable, secure, & up-to-date version of HRConvert2 that is available. 3. Just want to convert files. 4. Are not planning on contributing to development. 5. Are not planning on modifying the code or dependencies. Usually people who want to build their own Docker Image from source are people who; 1. Have modified the code or dependencies, and want to share the changes or deploy them on many servers. 2. Have a custom configuration that needs to be deployed on many servers. 3. Are contributing to a branch of HRConvert2 for distribution. If you truly want to build your own Docker Image from source this document will guide you through the Docker Image Build Instructions. ----------------------------------------------------------------------------------- -----STEP 1 - PUBLISHING A RELEASE----- Publishing the official image is automatic. Pushing a version tag is the entire procedure. 1. Make sure every version stamp in the source matches the version you are about to tag. 1a. $HRConvertVersion in convertCore.php, & $Version in Resources/versionInfo.php. 1b. $ConfigVersion in Resources/config.php & in Resources/Contract/config-template.php. That template & the Engine's, Resources/Engine/config-template.php, are what a new installation's config.php is written from, & $ConfigVersion is in the application's half. Both match $RequiredConfigVersion in convertCore.php rather than the tag. All three move together & only when a release adds or removes a setting in either half. 1c. $GuiVersion in every UI//uiVersionInfo.php, if the interfaces changed. 1d. $LanguageVersion in every language pack, if the strings changed. 1e. Run 'php convertCore.php --build --pins --write' to move every pin to the versions above, then 'php convertCore.php --build --pins', which must exit 0. $RequiredKernelVersion & $RequiredEngineVersion in convertCore.php are set by hand, because the build runs inside the kernel & the Engine & cannot rewrite what loads it. 1f. Run 'php convertCore.php -v' to confirm every component reports what you expect. 1g. A tag that does not match the source produces an image whose core refuses its own config. 2. Commit and push everything to the repository. 3. Tag the release and push the tag. 3a. Run 'git tag v#.#.#' 3b. Run 'git push origin v#.#.#' 4. The workflow at .github/workflows/docker-build.yml takes over from there. It will; 4a. Build linux/amd64 on ubuntu-latest and linux/arm64 on ubuntu-24.04-arm, each natively. 4b. Start each image and confirm it serves a page before calling it good. 4c. Push each image by its digest, then publish both under v#.#.#, #.#, # and latest. 5. Watch the run in the Actions tab of the repository. 5a. A cold build takes a long time, because FFMPEG & ImageMagick are built from source. 5b. A build where only later layers changed reuses the cache and finishes much faster. Each architecture keeps a cache of its own, so one never evicts the other. 5c. Until v4.1.7 the arm64 image was built under QEMU, which ran past GitHub's six hour limit for a job. A native arm64 runner is free for a public repository. 6. If the workflow fails, nothing is published. Fix the cause, delete the tag, and tag again. 6a. Run 'git tag -d v#.#.#' 6b. Run 'git push --delete origin v#.#.#' WHAT TRIGGERS A BUILD. FOUR THINGS, & ONLY TWO OF THEM PUBLISH. A version tag Builds, smoke tests & publishes v#.#.#, #.#, # and latest. A push to master Builds, smoke tests & publishes edge ONLY. latest does not move. A pull request Builds & smoke tests. Publishes nothing. workflow_dispatch Builds, smoke tests & publishes, because it is not a pull request. NOTE. A tagged release runs the workflow twice. The commit reaching master fires an edge build & the tag pointing at that same commit fires another. Both build the identical tree & the layer cache makes the second one cheap. NOTE. workflow_dispatch from a branch that is neither master nor a tag produces no tags at all & the push step fails. Launch it from master or from a tag. NOTE. THE IMAGE IS BUILT FROM THE CHECKOUT, NOT FROM GITHUB. An earlier Dockerfile cloned the repository & checked out a build argument, so the image never held the code being tested. A pull request could not build at all, since the merge commit it builds against does not exist in a plain clone. ----------------------------------------------------------------------------------- -----STEP 2 - BUILDING BY HAND----- Everything below is for building an image locally. This is not how the official image is published. Build by hand when you are testing a Dockerfile change, when you maintain a fork, or when you need an image the workflow will not produce. 1. Grab a cup of coffee. 2. Make sure you have Docker and the tools a multi platform build needs. 2a. Run 'sudo apt install docker.io docker-buildx qemu-user-static binfmt-support' 2b. Run 'docker run --privileged --rm tonistiigi/binfmt --install all' 2c. qemu-user-static is what allows an amd64 machine to build the arm64 image. 3. Before building, ALWAYS restart the Docker service. Doing so resolves countless errors. 3a. Run 'sudo service docker restart' 3b. Run 'sudo /etc/init.d/docker restart' 3c. Run 'sudo snap restart docker' 4. Create a builder. The default builder cannot perform a multi platform build. 4a. Run 'docker buildx create --name hrc2builder --use --bootstrap' 5. Build from the repository root, NOT from the Documentation/Build folder. 5a. The COPY instructions in the Dockerfile are relative to the build context. 5b. For one platform, run; docker buildx build --file Documentation/Build/Dockerfile --platform linux/amd64 --tag hrconvert2:test --progress=plain --load . 5c. For both platforms, run; docker buildx build --file Documentation/Build/Dockerfile --platform linux/amd64,linux/arm64 --tag hrconvert2:test --progress=plain . 5d. For a clean build that reuses nothing, add '--no-cache' 6. Grab another cup of coffee. The build process will take some time. 6a. FFMPEG is compiled from source and is the majority of the build time. 6b. FFMPEG is compiled rather than installed because it is built with -nonfree. A -nonfree build cannot be redistributed, so the packaged FFMPEG cannot be used. 6c. On a 16 core machine a clean single platform build takes roughly 25 minutes. 6d. The arm64 half is emulated and takes considerably longer than the amd64 half. 6e. Every source build works in a folder of its own under /var/tmp & removes it, so nothing it leaves reaches the image. Until v4.0.6 FFMPEG's build left its whole tree in Documentation/Build/ffmpeg-build in the web root, & every container started from that image refused to run anything as root, with error 28008. 6f. From v4.3.2 the install also builds HRConvert2's own Assimp, with build-assimp.sh & the patches beside it, which fetches Assimp's pinned commit from GitHub. It adds about a minute & a half on two x86 cores. The image installs no assimp-utils, & -v inside the container names the own build under /usr/local/libexec/hrconvert2/builds/assimp. ----------------------------------------------------------------------------------- -----STEP 3 - TEST THE IMAGE----- 1. Run 'docker run -d --name hrc2test -p 8080:80 -p 8443:443 --cap-add SYS_ADMIN hrconvert2:test' 2. Open a browser and navigate to 'http://localhost:8080' to test the converter. 3. Run 'docker exec hrc2test php /var/www/html/HRProprietary/HRConvert2/convertCore.php -v' 3a. This reports every component version and every dependency, and is faster than testing each conversion type by hand. 3b. Every dependency should report OK. Anything reporting FAILED is missing from the image. 4. Run 'docker logs hrc2test' to see anything the container printed on startup. 4a. The entrypoint prefixes every line it writes with [entrypoint], so its own progress is distinguishable from the output of the core & of the web server. 5. Run 'docker stop hrc2test && docker rm hrc2test' when finished. NOTE ON DIAGNOSING A FAILED SMOKE TEST. A curl exit code of 7 is CONNECTION REFUSED & means nothing is listening. That is a container that exited rather than an application that returned an error. An application error would answer with a 500 & curl would exit 22. The workflow polls for sixty seconds, detects an exited container immediately rather than waiting out a fixed sleep, & always prints the container state, the logs, the -v report & the tail of the HRConvert2 log before it fails. A container that is still running & never answered is one whose entrypoint has not handed the foreground to the web server yet. Its logs show how far it got, which is usually -fp. The -v report ends with -v's own exit code, & error 28008 there means root may not run the installation. The -fp lines in the logs say why. Until v4.0.6 the workflow followed any -v that failed with a line saying the container was not running, whatever its state. NOTE ON THE SYS_ADMIN CAPABILITY. Every conversion runs inside a bubblewrap sandbox, & a container cannot create the namespace that needs without '--cap-add SYS_ADMIN'. A container started without it refuses documents, e-books, SVG, drawings, models, audio, video, subtitles & streams, from v4.2.7, because each of their tools reads a file an upload names, & images, OCR, traces & Strip Metadata, from v4.3.1, because ImageMagick, Tesseract & mat2 are never run without a sandbox either. It runs every other conversion unprotected & logs a warning, or refuses it too where --Require Sandbox On Docker-- is TRUE in config.php. No process that converts or serves a user's file holds the capability, or any other. '--security-opt seccomp=unconfined' works instead on some hosts, as the Dockerfile says. The workflow tests with the capability, & the README & INSTALLATION_INSTRUCTIONS.txt ask for it. Until v4.0.0 this step used the seccomp option & said only OpenSCAD needed it, which was true before every dependency was sandboxed. This belongs in the Docker Hub description so operators know to add it. ----------------------------------------------------------------------------------- -----STEP 4 - PUSHING A HAND BUILT IMAGE----- Only necessary when you built by hand. The workflow pushes its own images. 1. On a computer with Docker Hub account linked, run 'docker push zelon88/hrconvert2:v#.#.#' 2. On a computer with Docker Hub account linked, run 'docker push zelon88/hrconvert2:latest' NOTE ON THE GITHUB CONTAINER REGISTRY. The workflow published to GHCR as well until v3.8.8 & no longer does. Pushing to it needs a package scope the workflow token does not carry by default, & the failure it produces reads as denied: permission_denied: read_package on a PUSH, which points at the wrong thing entirely. A second registry publishing an identical image earns nothing unless somebody pulls from it. Add it back deliberately, with a token that has the scope, rather than by default. ----------------------------------------------------------------------------------- -----NOTES----- 1. If you forget to tag your release, don't re-build it! Use the following procedure to add the missing tags. 1a. Run 'docker images' 1b. Copy the Image ID of the Docker Image you want to tag. 1c. Add a new tag to the existing image by running 'docker tag ########### zelon88/hrconvert2:v#.#.#' where ##### is the Image ID and v#.#.# is the version being tagged. 1d. To remove a tag, run 'docker rmi zelon88/hrconvert2:v#.#.#' 2. Adding the 'latest' tag is helpful to users. 3. The workflow needs two repository secrets to publish to Docker Hub. 3a. DOCKERHUB_USERNAME 3b. DOCKERHUB_TOKEN 3c. It needs no permission over GitHub packages & the publish job asks for none. 4. A Docker container is disposable. A Docker user updates by pulling a new image, not by running the built in updater. The updater exists for bare metal installations. 5. Everything a container must keep across a replacement lives outside the image. 5a. The data location, which holds every session and both copies of the install secret. 5b. Resources/config.php. 5c. Confirm both are on a volume before telling anyone to pull a new image. 6. An image built before v4.0.1 shipped the install secret it was built with, so every container started from it shares one secret. A data volume first filled by such an image keeps that secret after the image is replaced. Images from v4.0.1 onward ship none, & each container creates its own. Run this once in every container whose data location an older image filled. 6a. 'docker exec php /var/www/html/HRProprietary/HRConvert2/convertCore.php --rotate-secret -y' 6b. Every session in that container ends, which is what rotating a secret is for. -----------------------------------------------------------------------------------