DEV Community

Hardik Chotaliya
Hardik Chotaliya

Posted on • Originally published at hardikchotaliya.hashnode.dev on

How to Install Kiwi TCMS using Docker: Complete Guide for QA Professionals

#kiwitcmsdockerinstal #kiwitcms #dockerforqateams #dockerinstallation

Introduction to Kiwi TCMS

In todays fast-paced software development world, quality assurance (QA) teams need efficient tools to manage test cases and ensure reliable releases. Among the many test case management systems available, Kiwi TCMS stands out as an open-source, web-based platform designed for modern QA workflows.

Deploying Kiwi TCMS using Docker makes installation, configuration, and maintenance seamless, even for large teams. In this guide, well walk step by step through the Kiwi TCMS Docker Installation process while sharing tips to help QA professionals get started quickly.

What is Kiwi TCMS?

Kiwi TCMS is an open-source test case management system that helps QA teams organize test plans, manage test runs, track results, and integrate with CI/CD pipelines. It offers:

  • A web-based user interface for managing test cases

  • REST APIs for automation

  • Integrations with popular tools like Jenkins, GitHub, and Bugzilla

  • Real-time reporting and dashboards

Why QA Professionals Use Kiwi TCMS

QA engineers choose Kiwi TCMS because it:

  • Centralizes test management in one accessible platform

  • Improves collaboration between testers, developers, and product owners

  • Supports agile workflows and automation testing pipelines

  • Reduces overhead by being lightweight and easy to deploy

Benefits of Using Docker for Kiwi TCMS

Using Docker simplifies Kiwi TCMS deployment in multiple ways:

Kiwi TCMS + Docker Overview Diagram showing Kiwi TCMS connected to Docker containers (web + database)

  • Portability: Run Kiwi TCMS consistently across environments.

  • Quick Setup: No need to configure dependencies manually.

  • Isolation: Avoid conflicts with other applications.

  • Scalability: Spin up additional instances if required.

Prerequisites Before Installation

Before diving into the installation steps, make sure your system is prepared.

System Requirements

To run Kiwi TCMS in Docker smoothly, youll need:

  • A machine running Linux/macOS/Windows with WSL2

  • At least 2 GB of RAM and 2 CPU cores

  • Latest Docker Engine and Docker Compose installed

Verifying Docker and Docker Compose Installation

Check if Docker is installed and running:

docker --versiondocker-compose --version
Enter fullscreen mode Exit fullscreen mode

If both return valid versions, youre good to go!

Step-by-Step Kiwi TCMS Docker Installation

Step 1: Create a Project Directory 

mkdir ~/kiwi-tcmscd ~/kiwi-tcms
Enter fullscreen mode Exit fullscreen mode

This ensures a dedicated workspace for configuration and data storage.

Step 2: Download the Docker Compose Configuration

Kiwi TCMS provides a ready-to-use docker-compose.yml file.

Option A: Direct Download 

curl -O https://raw.githubusercontent.com/kiwitcms/Kiwi/master/docker-compose.yml
Enter fullscreen mode Exit fullscreen mode

Option B: Create Manually

If you prefer, create a file named docker-compose.yml and copy the default configuration from the official Kiwi TCMS GitHub repository.

Step 3: Start Kiwi TCMS Containers

Navigate to the project directory and run:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

This will:

  • Pull the required Docker images

  • Start Kiwi TCMS and MariaDB containers

  • Set up persistent volumes for database storage

Step 4: Verify Services are Running 

docker compose psdocker compose logs -f
Enter fullscreen mode Exit fullscreen mode

These commands help confirm that the containers are running without errors.

Step 5: Perform Initial Configuration

Before using Kiwi TCMS, you must initialize the system:

docker exec -it kiwi_web /Kiwi/manage.py initial_setup
Enter fullscreen mode Exit fullscreen mode

Youll be asked to provide:

  • Username (e.g., namelastname)

  • Email (name.lastname@company.com)

  • Password (minimum 10 characters)

  • Domain name (e.g., tms)

Step 6: Access Kiwi TCMS Dashboard

Once the setup is complete, open your browser:

  • HTTPS (recommended): https://localhost

  • HTTP: http://localhost (auto-redirects to HTTPS)

Special Considerations for macOS Users

Handling SSL Certificate Warnings

Since Kiwi TCMS uses a self-signed SSL certificate, Safari/Chrome will display a warning. To resolve:

  1. Select Advanced Proceed anyway

  2. Install the certificate from https://localhost/static/ca.crt into your macOS keychain

Firewall and Network Troubleshooting

If you face connectivity issues, verify:

  • macOS Firewall settings under System Preferences Security & Privacy Firewall

  • Docker network configuration

Best Practices for Kiwi TCMS Deployment

  • Secure your instance by updating default settings and using strong passwords

  • Manage user accounts with role-based access

  • Automate backups using Docker volumes and scheduled tasks

Common Errors and Troubleshooting Tips

  • Containers wont start: Run docker compose logs to diagnose issues

  • Database errors: Ensure MariaDB is running and accessible

  • SSL issues: Reinstall the certificate or use a trusted CA

Frequently Asked Questions (FAQs)

Q1. What is Kiwi TCMS best used for?

A: Its best for managing test cases, test runs, and QA team workflows.

Q2. Can Kiwi TCMS integrate with CI/CD tools?

A: Yes, it integrates with Jenkins, GitHub Actions, and Bugzilla.

Q3. Is Docker mandatory for Kiwi TCMS?

A: No, but Docker is the simplest and most reliable method of installation.

Q4. How do I back up my Kiwi TCMS data?

A: Use Docker volumes and regular docker export commands.

Q5. Does Kiwi TCMS support multiple users?

A: Yes, it supports role-based access for QA teams of any size.

Q6. How do I update Kiwi TCMS in Docker?

A: Pull the latest image and restart containers with docker compose up -d.

Conclusion: Why Kiwi TCMS Docker Installation is Ideal for QA Teams

Deploying Kiwi TCMS using Docker is a fast, secure, and scalable approach that suits QA professionals of all experience levels. From installation to SSL handling, this guide equips you with everything needed to get started.

By combining the power of Docker with the flexibility of Kiwi TCMS , your QA team can efficiently manage test cases, streamline workflows, and improve software quality.

]]>

Top comments (0)