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.

1. 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"
2. Install WSL and Debian:
   • Run: wsl --install
   • If Debian is not automatically installed, run: wsl --install -d Debian
3. Set WSL version 2 as default: wsl --set-default-version 2
4. Important: After installation, WSL will prompt you to create a user account. This will be your main Linux user - remember these credentials!
5. (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

1. Install required packages:
   • brew install podman podman-compose
2. 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):

1. 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:

1. 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:

1. podman machine stop; podman machine set --rootful && podman machine start

Performance Tuning

If you encounter performance issues or container crashes:

1. Locate podman machine config:
   • $HOME/.config/containers/podman/machine/qemu/podman-machine-default.json
2. Increase memory allocation:
   • Change -m flag value to 8196 (or at least 4096)
   • Update Memory field to match
3. 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

1. Install Colima via Homebrew:
   • brew install colima docker docker-compose
2. 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

1. Check Docker availability:
   • docker ps
2. 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

1. Install dependencies:
   • For Ubuntu/Debian: sudo apt-get install docker.io docker-compose
   • For Arch: sudo pacman -S docker docker-compose
2. Install Colima:
   • Download latest release from GitHub
   • Make it executable: chmod +x colima
   • Move to PATH: sudo mv colima /usr/local/bin/
3. Start Colima:
   • colima start --cpu 4 --memory 8 --disk 100

Verification and Setup

1. Verify Docker is working:
   • docker ps
2. 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

1. Open VS Code
2. Click the Remote Explorer icon in the left sidebar
3. Look for your container (usually named koha-koha-1 or kohadev-koha-1)
4. Right-click and choose "Attach in Current Window" or "Attach in New Window"
5. Configure instance user¹:
   1. Open Command Palette (View → Command Palette)
   2. Select "Dev Containers: Open Named Container Configuration File"
   3. Add: "remoteUser": "kohadev-koha"²
   4. Reload window
6. Open folder: /kohadevbox/koha

Method 2: Using Keyboard Shortcuts

1. Press Ctrl/Cmd + Shift + P
2. Choose "Dev Containers: Attach to Running Container"
3. Select your Koha container
4. Configure instance user¹:
   1. Press Ctrl/Cmd + Shift + P
   2. Select "Dev Containers: Open Named Container Configuration File"
   3. Add: "remoteUser": "kohadev-koha"²
   4. Press Ctrl/Cmd + Shift + P and select "Developer: Reload Window"
5. Press Ctrl/Cmd + O and enter /kohadevbox/koha

¹ Container configuration is saved for all containers with the same name ² User configuration ensures correct file ownership and resolves GitLens safety warnings

Final Setup

1. Install Perl Navigator in container
2. Configure Perl Navigator settings as needed
3. Important: Code formatting and linting will use:
   • .perlcriticrc
   • .perltidyrc

Troubleshooting

Common Issues

Permission Errors

1. Restart services in this order:
   1. Stop containers: ktd down
   2. Restart Docker/Podman service
   3. Start containers: ktd up

Container Not Found

1. Container names might vary:
   1. Look for koha-koha-1 or kohadev-koha-1
   2. Use docker ps or podman ps to check actual names

MPM_ITK Error

Usually resolved by:

1. ktd down
2. Restart Docker/Podman
3. 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:

1. The default memory allocation (2048M) may not be sufficient
2. Recommended memory allocation: 8196M
3. Location of config file: $HOME/.config/containers/podman/machine/qemu/podman-machine-default.json
4. 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 ;).