Koha-testing-docker

Koha-testing-docker (or ktd for short) is a replacement for KohaDevBox. It is the recommended tool for setting up an environment to run tests, sign off, do development etc.

Get it

https://gitlab.com/koha-community/koha-testing-docker

Using koha-testing-docker for development

Note: This has currently been tested succesfully with Linux [Debian, Arch], macOS [Ventura, Sonoma] and Windows [10, 11].

One easy way to setup an IDE-ish experience w/ koha-testing-docker works something like this.

First you'll need VSCode (this might also work w/ VSCodium or Code - OSS but this has yet to be tested).

You'll need the following extensions:

Microsoft's Dev Containers
bscan's Perl Navigator

Got koha-testing-docker running?

If you don't have koha-testing-docker up and running yet, you should go to the repository and follow the steps in the README.md.

Using the Dev Containers extension

It’s actually super straightforward.

The clicky way

Open VSCode
Open the Dev containers or Remote Explorer tab
Right click the koha-koha-1 container
Choose Attach in Current Window or Attach in New Window from the context menu
Now that you are inside the container environment, let's configure the instance user to be the default for all operations¹
1. Open the command palette via View → Command Palette
2. Type Dev Containers: Open and choose the entry Dev Containers: Open Named Container Configuration File
3. Insert the following into the object "remoteUser": "kohadev-koha" ²
4. Open the command palette via View → Command Palette
5. Type Developer: Reload and choose Developer: Reload Window
Click on Open Folder
Enter /kohadevbox/koha

The right way ;)

Open VSCode
Hit the shortcut Ctrl/Cmd + Shift + P
Type Dev Containers and choose the entry Dev Containers: Attach to Running Container…
Choose the koha-koha-1 container
Now that you are inside the container environment, let's configure the instance user to be the default for all operations¹
1. Open the command palette again with Ctrl/Cmd + Shift + P
2. Type Dev Containers: Open and choose the entry Dev Containers: Open Named Container Configuration File
3. Insert the following into the object "remoteUser": "kohadev-koha" ²
4. Open the command palette again with Ctrl/Cmd + Shift + P
5. Type Developer: Reload and choose Developer: Reload Window
Hit Ctrl/Cmd + O and enter /kohadevbox/koha

_{1 We do this once using the named container configuration file and will have these settings set on all containers named koha-koha-1 (for example) when spun up.}

_{2 Now creating a new file should get the correct users assigned. It also removes an issue with GitLens extension complaining about using an unsafe repository because of the different users.}

There’s one more thing

The last thing you’ll need to do is to install the Perl Navigator extension into the container. Just open the extensions tab and click Install in Container koha/koha-testing...

You’re good to go

You can now configure Perl Navigator's settings to your liking and find all the definitions you want! Formatting and Linting is already working using the .perlcriticrc and .perltidyrc files in the project root.

Please tidy your code before submitting patches :D

Additional tips

If you are using the GitLens extension, it will be much happier if you have a clean state in your repository.

To achieve that, you can ignore the .vscode/ directory by adding it to .git/info/exclude

How to install koha-testing-docker on Windows

Install/Activate Windows Subsystem for Linux (WSL)

Open Powershell with admin privileges by pressing Win + X or through the app launcher.
Type wsl --install and hit enter. This will install WSL and prompt you to choose a Linux distribution to install. You can choose Debian, either through the Microsoft Store or by typing wsl --install -d Debian.
Set the default WSL version to 2 by typing wsl --set-default-version 2.
(Optional) Install the new Windows Terminal which allows you to open a shell on your installed Linux distributions. You can install it from the Microsoft Store.

Create a new user with sudo access

Type useradd <USER> and replace <USER> with the name of your choice.
Add the new user to the sudo group by typing usermod -aG sudo $USER.

Install Docker

Follow the official guide to install Docker on Debian: [1]
Verify that everything is installed correctly by typing docker run hello-world.

Get necessary files to run the containers

Create a new directory called git in your home directory by typing mkdir ~/git.
Change to the new directory by typing cd ~/git.
Clone the koha-testing-docker repository by typing git clone https://gitlab.com/koha-community/koha-testing-docker.git.
Clone the Koha repository by typing git clone https://github.com/Koha-Community/Koha.git.
Change the ownership of the koha-testing-docker and Koha directories to the new user by typing sudo chown -R $USER:$USER koha-testing-docker Koha.
Copy the default .env file to a new file called .env by typing cp koha-testing-docker/.env koha-testing-docker/.env.
Edit the .env file by typing nano koha-testing-docker/.env and change the KOHA_IMAGE variable from main to main-bullseye.
Save and exit by typing CTRL+X, then Y, then ENTER.

If you followed the guide, you should have a running koha-testing-docker now and be able to access Koha on localhost:8080 for the OPAC or localhost:8081 for the staff client.

How to use koha-testing-docker with podman

Keep in mind that podman is a Red Hat product and the company has shown a questionable stance towards open-source lately.
Disclaimer: Everything below was tested on an Apple M1 chip. If you're on an intel mac things might differ, especially regarding the default machine. If you're using a linux box arm or x86_64 things will definitely differ!

Install and setup podman on macOS

I'd advise that you use homebrew by running brew install podman podman-compose
You'll be greeted by a message stating that podman needs a linux kernel to run containers locally. To set that up on macOS, you can either install Podman Desktop via homebrew brew install podman-desktop or start a podman machine via the CLI podman machine init, which initializes your machine by fetching fedora-coreos to provide the linux kernel. Now you can start it by running podman machine start.
The machine will likely greet you with some suggestions regarding the podman-mac-helper. This system helper service essentially exposes podman via the docker API socket.
1. If you're not planning to use docker on the machine you're running podman on, you should enable it by running sudo /opt/homebrew/Cellar/podman/4.8.1/bin/podman-mac-helper install && podman machine stop; podman machine start.
2. If you plan to use podman and docker in parallel you should not enable it. If you don't enable it, you can still export the DOCKER_HOST environment variable to get it working like so export DOCKER_HOST='unix:///Users/$USER/.local/share/containers/podman/machine/qemu/podman.sock'.
Note that on macOS, podman uses a qemu machine by default if your architecture is arm64.
The next note podman provides is regarding the rootful state of the machine. While testing I ran into permission errors when using the rootless state so I'd advise to enable it by running podman machine stop; podman machine set --rootful && podman machine start.

Starting up koha-testing-docker

I'm going to assume that if you are at this point you have the environment set up to run koha-testing-docker. If not you should go to the repository and follow the steps in the README.md.
By default podman mounts the $USER dir. I noticed that on errors the podman machine unmounts those directories, which includes /Users/$USER/path/to/koha. This breaks startup of the koha container because the $SYNC_DIR doesn't exist on the podman machine. That's why I always run cd $KTD_HOME && podman machine stop; podman machine start; podman-compose -f docker-compose-light.yml -p koha down; podman-compose -f docker-compose-light.yml -p koha up # -d. This will pull all the images and log what you're used to from docker (either directly if you didn't use the -d flag or under podman logs -f koha_koha_1).
If you run into processes randomly getting killed at startup, for example $webpack --mode development, or getting signal 9s on plack when running the koha_koha_1 container, the reason I determined was the default settings for qemu in the podman-default-machine.json. The default configuration allocates only 2048M of memory to qemu which doesn't seem to suffice for running a stable koha instance with the additional virtiualization overhead. You can alleviate this issue by just dedicating more memory. I use 8196M and koha runs stable. You can also dedicate some more cores if you have them to spare. Podman uses CPUS/2 by default.
To make these changes find the previously mentioned podman-default-machine.json typically located at $HOME/.config/containers/podman/machine/qemu/podman-machine-default.json and increase the memory in the cli flags for qemu and the podman machine configuration.
1. First edit the value after the -m flag which is probably currently set to 2048. I guess 4G should be fine but I use 8196.
2. Secondly edit the value of the Memory field. It controls how much memory podman expects to be available. It's probably also set to 2048 and I set it to 8196 as well.
Only setting the qemu flag works, but I think the second step should also be undertaken to circumvent potential issues.

You're good to go test

I suspect that this setup isn't perfect. So take everything laid out here with a grain of salt. But I think we can work out upcoming issues eventually and get this to be as stable as docker.

Alternatives to Docker Desktop

Docker Desktop may appear convenient for local development using docker compose. However, there are cases where it may not be the ideal choice, especially due to licensing constraints. In some situations, a purely command-line interface (CLI) solution may not be readily available or may require a more manual setup.
To address these concerns, here is a list of alternatives that have been proven to work effectively with koha-testing-docker for docker compose-based development.

Tool	License	Distributor	Platforms	Features
Rancher Desktop	Apache 2.0	Rancher by SUSE	Linux macOS (Apple Silicon) macOS (Intel) Windows (x86_64)	Local Kubernetes Cluster Kubernetes Development Environment Docker Integration Helm Chart Support GitOps Capabilities Multi-Cluster Management Cross-Platform Compatibility User-Friendly GUI Extensibility
Colima	MIT	abiosoft (Abiola Ibrahim)	Linux macOS	Intel and M1 Macs support Simple CLI interface Docker and Containerd support Port Forwarding Volume mounts Kubernetes Multiple instances