Koha-testing-docker

= koha-testing-docker =
koha-testing-docker (or ktd for short) is a replacement for KohaDevBox. This document will guide you through setting up the preferred testing and development environment for Koha using koha-testing-docker.
What you'll get:
* A complete development environment for Koha
* Ability to run tests and sign off patches
* Integration with VS Code for efficient development
* Access to Koha's OPAC (port 8080) and staff client (port 8081)
Note: This setup has been tested successfully on:
* Linux (Debian, Arch)
* macOS (Ventura, Sonoma, Sequoia)
* Windows (10, 11)
== Quick Reference ==
* Main Repository: koha-testing-docker
* Official Documentation: README.md
* Hardware Requirements:
** x86_64 or arm64v8 system (Apple M1-M4, AWS EC2 Graviton)
** Minimum 2.6 GiB free RAM (4+ GiB recommended)
** Additional 2 GiB RAM if using Elasticsearch
== Installation Guide ==
=== Windows Installation ===
Important: All commands after WSL setup should be run within your WSL Debian environment, not in Windows PowerShell.
==== Step 1: Windows Subsystem for Linux (WSL) Setup ====
WSL allows you to run a Linux environment directly on Windows, which is necessary for Docker and Koha development.
# Open PowerShell with admin privileges:
#* Press Win + X and select "Windows PowerShell (Admin)" or
#* Search for "PowerShell" in the Start menu, right-click, and select "Run as administrator"
# Install WSL and Debian:
#* Run: wsl --install
#* If Debian is not automatically installed, run: wsl --install -d Debian
# Set WSL version 2 as default: wsl --set-default-version 2
# Important: After installation, WSL will prompt you to create a user account. This will be your main Linux user - remember these credentials!
# (Recommended) Install Windows Terminal from Microsoft Store for better WSL integration
==== Step 2: Basic Environment Setup ====
Follow the official setup guide for:
* Setting up environment variables
* Cloning repositories
* Configuring Docker
=== macOS Installation ===
==== Option 1: Using Podman ====
Podman is a Docker alternative that doesn't require root privileges.
===== Initial Setup =====
# Install required packages:
#* brew install podman podman-compose
# Initialize and start podman:
#* podman machine init
#* podman machine start
===== Podman Configuration =====
Choose ONE of the following options:
Option A: Enable podman-mac-helper (if not using Docker):
# Install helper and restart:
#* sudo /opt/homebrew/Cellar/podman/4.8.1/bin/podman-mac-helper install
#* podman machine stop; podman machine start
Option B: Configure for parallel Docker usage:
# Add to shell configuration (~/.zshrc or ~/.bash_profile):
#* export DOCKER_HOST='unix:///Users/$USER/.local/share/containers/podman/machine/qemu/podman.sock'
===== Enable Rootful Mode =====
Required to avoid permission issues:
# podman machine stop; podman machine set --rootful && podman machine start
===== Performance Tuning =====
If you encounter performance issues or container crashes:
# Locate podman machine config:
#* $HOME/.config/containers/podman/machine/qemu/podman-machine-default.json
# Increase memory allocation:
#* Change -m flag value to 8196 (or at least 4096)
#* Update Memory field to match
# Adjust CPU allocation if needed (default is CPUS/2)
==== Option 2: Using Colima ====
Colima is a lightweight alternative to Docker Desktop that provides Docker and Kubernetes.
===== Initial Setup =====
# Install Colima via Homebrew:
#* brew install colima docker docker-compose
# Start Colima with recommended settings:
#* colima start --cpu 4 --memory 8 --disk 100
Note: Adjust CPU, memory, and disk values based on your system capabilities.
===== Verification =====
# Check Docker availability:
#* docker ps
# If successful, follow the official KTD setup guide
==== Option 3: Using Docker Desktop ====
See the official Docker Desktop installation guide.
After installation, follow the official KTD setup guide.
=== Linux Installation ===
==== Option 1: Using Docker Engine ====
Follow the official Docker Engine installation guide for your distribution.
==== Option 2: Using Colima ====
Colima provides a consistent experience across Linux and macOS.
===== Initial Setup =====
# Install dependencies:
#* For Ubuntu/Debian: sudo apt-get install docker.io docker-compose
#* For Arch: sudo pacman -S docker docker-compose
# Install Colima:
#* Download latest release from GitHub
#* Make it executable: chmod +x colima
#* Move to PATH: sudo mv colima /usr/local/bin/
# Start Colima:
#* colima start --cpu 4 --memory 8 --disk 100
===== Verification and Setup =====
# Verify Docker is working:
#* docker ps
# Follow the official KTD setup guide
==== Option 3: Using Podman ====
Follow your distribution's instructions for installing Podman.
== Using KTD ==
=== Basic Commands ===
KTD provides a convenient wrapper script for common operations. Here are the most used commands:
* Start KTD: ktd up
* Access Koha container (instance user): ktd --shell
* Access database shell: ktd --dbshell
* View logs: ktd --logs
* Stop KTD: ktd down
For a complete list of commands, see the official documentation.
== Development Environment Setup ==
=== VS Code Integration ===
VS Code provides a powerful development environment for Koha when properly configured.
==== Required Extensions ====
Install these extensions from VS Code marketplace:
* Dev Containers by Microsoft
** Enables working directly inside Docker containers
* Perl Navigator by bscan
** Provides Perl language support and navigation
==== Setting up Dev Containers ====
===== Method 1: Using GUI =====
# Open VS Code
# Click the Remote Explorer icon in the left sidebar
# Look for your container (usually named koha-koha-1 or kohadev-koha-1)
# Right-click and choose "Attach in Current Window" or "Attach in New Window"
# Configure instance user1:
## Open Command Palette (View → Command Palette)
## Select "Dev Containers: Open Named Container Configuration File"
## Add: "remoteUser": "kohadev-koha"2
## Reload window
# Open folder: /kohadevbox/koha
===== Method 2: Using Keyboard Shortcuts =====
# Press Ctrl/Cmd + Shift + P
# Choose "Dev Containers: Attach to Running Container"
# Select your Koha container
# Configure instance user1:
## Press Ctrl/Cmd + Shift + P
## Select "Dev Containers: Open Named Container Configuration File"
## Add: "remoteUser": "kohadev-koha"2
## Press Ctrl/Cmd + Shift + P and select "Developer: Reload Window"
# Press Ctrl/Cmd + O and enter /kohadevbox/koha
1 Container configuration is saved for all containers with the same name
2 User configuration ensures correct file ownership and resolves GitLens safety warnings
==== Final Setup ====
# Install Perl Navigator in container
# Configure Perl Navigator settings as needed
# Important: Code formatting and linting will use:
#* .perlcriticrc
#* .perltidyrc
== Troubleshooting ==
=== Common Issues ===
==== Permission Errors ====
# Restart services in this order:
## Stop containers: ktd down
## Restart Docker/Podman service
## Start containers: ktd up
==== Container Not Found ====
# Container names might vary:
## Look for koha-koha-1 or kohadev-koha-1
## Use docker ps or podman ps to check actual names
==== MPM_ITK Error ====
Usually resolved by:
# ktd down
# Restart Docker/Podman
# ktd up
== Additional Tips ==
=== GitLens Users ===
For better performance and fewer warnings:
* Add .vscode/ to .git/info/exclude
* Keep repository in a clean state
=== Docker Desktop Alternatives ===
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.
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
=== Performance Tips ===
==== Podman Memory Issues ====
If you run into processes randomly getting killed at startup (e.g., $webpack --mode development) or signal 9s on plack:
# The default memory allocation (2048M) may not be sufficient
# Recommended memory allocation: 8196M
# Location of config file: $HOME/.config/containers/podman/machine/qemu/podman-machine-default.json
# Edit both:
#* -m flag value
#* Memory field value
==== VSCode Alternatives ====
While VSCode is recommended, you might also use:
* VSCodium
* Code - OSS
Note: These alternatives haven't been extensively tested with the Dev Containers extension ;).
Category:Development