Koha Testing Docker on Windows WSL: Common Setup Problems and Fixes

Koha Testing Docker on WSL: Common Setup Problems and Fixes
While setting up Koha Testing Docker (KTD) on Windows using WSL and Docker Desktop, I encountered several problems related to Docker configuration, port conflicts, and accessing Koha through the browser.
This guide summarizes the problems I encountered, how I diagnosed them, and how I fixed them.
The goal is to provide a practical troubleshooting guide for anyone setting up Koha Testing Docker on Windows with WSL and Docker Desktop.

Environment

My setup consisted of:
Windows
WSL (Ubuntu)
Docker Desktop
Koha Testing Docker (KTD)

1. ktd pull Could Not Find Docker

Problem

When I initially ran:
ktd pull

KTD produced an error similar to:
.../ktd: line 725: /usr/bin/docker: No such file or directory

At first, this was confusing because Docker was already installed and working.

I checked:
which docker

and received:
/usr/bin/docker

I also ran:
/usr/bin/docker --version

which successfully displayed the installed Docker version.
Therefore, Docker itself was not missing.

Cause

The problem was related to how the KTD configuration was being read.
The .env file was not being interpreted correctly, and it also contained Windows-style CRLF line endings.

I checked the file using:
cat -v .env

If the output contains ^M at the end of lines, that indicates Windows-style line endings.

For example:
DOCKER_BINARY=/usr/bin/docker^M

The ^M is the carriage return character from Windows line endings.

Fix

I made sure that .env contained:
DOCKER_BINARY=/usr/bin/docker

I also converted the .env file to Unix-style line endings.
After fixing the configuration, I ran:
ktd pull

again, and it worked successfully.

Lesson

When using configuration files between Windows and WSL/Linux, always check for CRLF line endings if a shell script behaves unexpectedly.

2. Port 8080 Was Already in Use

Problem

After successfully pulling the KTD images, I tried to start the environment:

ktd up -d

However, Docker returned an error similar to:

ports are not available: exposing port TCP 0.0.0.0:8080

This indicated that port 8080 on the Windows host was already being used by another application.

Finding Which Process Was Using the Port

Since the host operating system was Windows, I checked the port from PowerShell:
netstat -ano | findstr :8080

This showed the process ID (PID) using port 8080.

I then identified the process with:
Get-Process -Id <PID>

In my case, the process was:
TNSLSNR

TNSLSNR is associated with Oracle Database's listener service.

Therefore, port 8080 could not be assigned to Koha.

Fix

Instead of stopping the Oracle service, I changed the Koha port mapping so that Koha would use other available ports.
The final compose/local_ports.yml configuration was:

services:
    koha:
        ports:
            - "8082:8082"
            - "8081:8081"

This resulted in:
8081 → Koha Staff Interface
8082 → Koha OPAC
I then ran:
ktd up -d

The containers started successfully.

Lesson

When Docker reports that a port is already in use, first identify which process is using it. If the port belongs to another important service, changing the Docker port mapping is often safer than stopping that service.

3. ERR_EMPTY_RESPONSE When Opening the OPAC

Problem

After the containers started successfully, I tried accessing the Koha OPAC through the browser.

Sometimes the browser displayed:
ERR_EMPTY_RESPONSE

At this point, it was not clear whether the problem was caused by:

• Docker
• Koha
• Apache
• The database
• Port configuration
• Windows/WSL networking
• Hostname resolution

Instead of reinstalling Koha, I checked each layer separately.

Step 1: Check the KTD Containers

First, I checked whether the required containers were running:
docker ps

The Koha, MariaDB, and Memcached containers were running.
This confirmed that the basic Docker environment was up.

Step 2: Check Apache

Next, I checked the Apache service inside the Koha container:
docker exec -it kohadev-koha-1 service apache2 status

Apache was running successfully.
Therefore, the problem was not simply that the web server had stopped.

Step 3: Check Apache Virtual Hosts

I then checked Apache's virtual-host configuration:
docker exec -it kohadev-koha-1 apache2ctl -S

The configuration showed:
*:8082 kohadev.myDNSname.org
*:8081 kohadev-intra.myDNSname.org

This confirmed that Apache had virtual hosts configured for both Koha interfaces.
The configuration therefore matched the intended port setup:
8081 → Staff Interface
8082 → OPAC

Step 4: Verify Koha Is Listening on the Correct Ports

Next, I checked which ports were actually listening inside the Koha container:
docker exec -it kohadev-koha-1 ss -lntp

Apache was listening on:
0.0.0.0:8081
0.0.0.0:8082

This was important because it confirmed that Apache was not only configured for those ports, but was actually listening on them.
I then tested both services directly from inside the container:
docker exec -it kohadev-koha-1 curl -I http://localhost:8081

and:
docker exec -it kohadev-koha-1 curl -I http://localhost:8082

Both returned:
HTTP/1.1 200 OK

This confirmed that Koha and Apache were responding correctly inside the container.

Step 5: Verify the Koha Database

Since the web server was responding, I also checked whether the Koha instance and database had been initialized correctly.
First, I checked the available Koha instances:
docker exec -it kohadev-koha-1 koha-list

The command returned:
kohadev

This confirmed that the kohadev Koha instance existed.
I then checked the MariaDB databases:
docker exec -it kohadev-koha-1 \
mysql -h db -u root -ppassword \
-e "SHOW DATABASES;"

The database:
koha_kohadev

was present.
Finally, I checked its tables:
docker exec -it kohadev-koha-1 \
mysql -h db -u root -ppassword \
-e "USE koha_kohadev; SHOW TABLES;"

This returned the Koha database tables.
Therefore, the database was properly created and populated.
This ruled out problems such as:

• Missing Koha database
• Missing Koha instance
• Uninitialized database
• Empty database

Step 6: Verify the Connection From Windows
Since Koha was working correctly inside the container, I checked whether Windows could access the services through the mapped ports.
From Windows PowerShell, I ran:
_curl.exe -I http://localhost:8081_

and:
_curl.exe -I http://localhost:8082_

Both returned:
HTTP/1.1 200 OK

I then tested the actual Koha hostnames.
For the Staff Interface:
_curl.exe -I http://kohadev-intra.myDNSname.org:8081_

For the OPAC:
curl.exe -I http://kohadev.myDNSname.org:8082

Both returned:
HTTP/1.1 200 OK

This confirmed that the complete connection path was working:
Windows
↓
Docker port mapping
↓
Koha container
↓
Apache
↓
Koha

Result

The diagnostic checks showed that Koha itself was working correctly.
The following were all confirmed:
Docker containers were running.
Apache was running.
Apache virtual hosts were configured correctly.
Apache was listening on ports 8081 and 8082.
Koha responded with HTTP/1.1 200 OK inside the container.
The kohadev Koha instance existed.
The koha_kohadev database existed and contained Koha tables.
Windows could reach both ports.
The Koha hostnames also returned HTTP/1.1 200 OK.
Therefore, the ERR_EMPTY_RESPONSE was not caused by a broken Koha installation or database.
The important lesson was to diagnose the problem layer by layer instead of immediately reinstalling the environment.

4. Final Working Configuration

After resolving the port conflict and verifying the services, the final port configuration was:

services:
    koha:
        ports:
            - "8082:8082"
            - "8081:8081"

The two Koha interfaces were accessible as follows.
Staff Interface
http://kohadev-intra.myDNSname.org:8081

This opens the Koha Staff Interface, where librarians or administrators can manage the library system.
OPAC
http://kohadev.myDNSname.org:8082

This opens the Koha Online Public Access Catalog (OPAC).

5. Useful Troubleshooting Commands

The following commands were useful throughout the troubleshooting process.
Check Docker
which docker
docker --version

Check KTD Containers
docker ps

Check Koha Instance
docker exec -it kohadev-koha-1 koha-list

Check Apache
docker exec -it kohadev-koha-1 service apache2 status

Check Apache Virtual Hosts
docker exec -it kohadev-koha-1 apache2ctl -S

Check Listening Ports
docker exec -it kohadev-koha-1 ss -lntp

Test Koha From Inside the Container
docker exec -it kohadev-koha-1 curl -I http://localhost:8081
docker exec -it kohadev-koha-1 curl -I http://localhost:8082

Check Whether a Port Is Already Occupied on Windows
From PowerShell:
netstat -ano | findstr :8080

Then identify the process:
Get-Process -Id

Test Koha From Windows
curl.exe -I http://localhost:8081
curl.exe -I http://localhost:8082

And test the hostnames:
curl.exe -I http://kohadev-intra.myDNSname.org:8081
curl.exe -I http://kohadev.myDNSname.org:8082

Conclusion

Setting up Koha Testing Docker on Windows with WSL and Docker Desktop involved several issues, but each one could be isolated by checking the system layer by layer.

The main problems were:

KTD could not correctly use Docker
→ The .env configuration and Windows-style line endings were corrected.

Port 8080 was already occupied

→ The process using the port was identified as TNSLSNR, and Koha was moved to ports 8081 and 8082.

The browser sometimes showed ERR_EMPTY_RESPONSE
→ Instead of reinstalling Koha, the containers, Apache, virtual hosts, listening ports, database, and Windows connection were checked individually.

The overall troubleshooting approach was:

Docker
↓
Port availability
↓
KTD containers
↓
Apache
↓
Apache virtual hosts
↓
Listening ports
↓
Koha instance
↓
Database
↓
Windows connection
↓
Browser

The most important lesson is that troubleshooting each layer separately is much more effective than immediately reinstalling the entire environment.
If Koha is not opening, first determine where the connection fails. Once each layer is verified, the actual cause becomes much easier to identify.