Docker containers for automated OS setup, build config, compile, test, and install
for GnuCash v3+ binaries and docs
Copyright (C) 2019 Dale Phurrough [email protected]
- You need a Docker host/engine on a Linux-based OS. Other host OS are not yet supported. Docker has free and easy instructions
- Strongly recommend you have
docker-compose
installed git clone
this repo into a folder on your host
In the folder containing these files, run the following command. This will start a Ubuntu 18.04 container that will configure, compile, test, and install GnuCash all safely within the container.
docker-compose up -d ubuntu-18.04
You can view the progress using a well-known command like:
docker logs gnucashbuild-ubuntu-18.04
Do you have a computer with X11 and allow remote X11 applications? If yes, you can run your newly compiled GnuCash with the following commands.
docker exec -ti gnucashbuild-ubuntu-18.04 bash # after this, you are inside the container
cd /opt/bin
export DISPLAY=mycomputer:0.0 # replace mycomputer with hostname or IP address
./gnucash
Prebuilt containers are on DockerHub as diablodale/gnucashbuilder:<OS_DIST_TAG>
with the same names as in the docker-compose.yml
. These containers are the built Dockerfiles. You could use these to docker run
a fresh compile, test, and/or install of GnuCash.
# examples pulling three of the prebuilt containers from DockerHub
docker pull diablodale/gnucashbuilder:centos-7
docker pull diablodale/gnucashbuilder:debian-10
docker pull diablodale/gnucashbuilder:ubuntu-18.04
The Dockerfiles (or pulled containers from DockerHub) can be used direct with docker run
or more easily with
docker-compose
. The docker-compose.yml
included is configured for major releases
of Ubuntu, Debian, Arch, CentOS, Fedora, and openSUSE Linux. Use the same Quick Start
command above with any of the OS in the file.
You can automate the install and have it appear on any desktop running X11
by setting GNC_PHASES
and DISPLAY
. Inspect this file to see how new
operating systems can be added or options changed to meet your needs.
docker-compose
documentation can help you
better understand. Naturally, you are welcome to hack docker-compose.yml
. These
are the build arguments and environment variables specific to this solution.
Build Argument | Description | Example |
---|---|---|
LANG | Override the default locale en_US.UTF-8 . Container will install your locale plus en_US, en_GB, fr_FR, de_DE. |
LANG=es_ES.UTF-8 |
OS_DIST | Docker image name | OS_DIST=ubuntu |
OS_TAG | Version of Docker image | OS_DIST=18.04 |
Environment Variable | Description | Example |
---|---|---|
BUILDTYPE | Override the default make build tool for the OS. Only cmake-make and cmake-ninja are supported. To prevent building, set to any other value, e.g. stop . |
BUILDTYPE=stop |
DISPLAY | Set DISPLAY environment variable for X11; enables GnuCash inside container to display on host/remote X11. |
DISPLAY=192.168.1.5:0.0 |
GNC_EXIT_WITH_RESULT | Set to 1 to immediately stop/exit container with results. Container's log retains details. Good for DevOps and CI like Travis. |
GNC_EXIT_WITH_RESULT=1 |
GNC_GIT_CHECKOUT | GnuCash git branch, commit, tag to clone and checkout into the container's /build directory. It will abort if /build already contains files. | GNC_GIT_CHECKOUT=3.5 |
GNC_IGNORE_BUILD_FAIL | Set to 1 to ignores build errors/failures. Container's log retains details. |
GNC_IGNORE_BUILD_FAIL=1 |
GNC_PHASES | Comma-separated phases to execute. Default is build,test .build : compile GnuCash executableinstall : install GnuCash in the containertest : compile and run unit tests |
GNC_PHASES=build,install |
PLATFORM_CMAKE_OPTS | Gnucash Build Options separated by spaces | -DWITH_PYTHON=ON |
TZ | Override the default timezone Etc/UTC . Can be any timezone identifier from tzdata in /usr/share/zoneinfo, e.g. Japan , Europe/Berlin , Australia/Sydney , etc. |
TZ=Australia/Sydney |
By default, each container has its own private copy of the OS, build tools, GnuCash source files, compiled code, and test files. Docker has easy methods to mount host files/folders into the container.
You can store and manage your GnuCash source files on your host and mount them into the container so that container can compile them.
- Builds always occur from the container's
/gnucash
folder. It should contain the GnuCash source code. - The GnuCash build process requires read+write access to this
/gnucash
folder. - The GnuCash build process alters/create some files in the source code folder. You may encounter difficult to isolate issues if you mount the same source code folder into multiple containers and simultaneously compile.
# docker-compose.yml
volumes:
- /home/user1/source/gnucash:/gnucash
# bash
docker run -v /home/user1/source/gnucash:/gnucash gnucashbuild:ubuntu-16.04
You can receive the result of the build process on your host. This is done by
mounting a folder on your host into the container at /build
.
- Builds results always go to the container's
/build
folder. - The GnuCash build process requires read+write access to this
/build
folder. - The GnuCash build process substantially alters this folder. You may encounter difficult to isolate issues if you mount the same build folder into multiple containers and simultaneously compile.
# docker-compose.yml
volumes:
- /home/user1/build/gnucash:/build
# bash
docker run -v /home/user1/build/gnucash:/build gnucashbuild:ubuntu-16.04
- docker-compose file version 2.4 enables several of the below features
init: true
provides a init process handler for clean Linux startup/shutdowntty: true
andstdin_open: true
are set to support running bash at the end of the Linux build process- VS Code Remote Development works well with this Docker setup.