Deploying Tuleap

Introduction

Tuleap is an open-source application lifecycle management (ALM) platform that provides comprehensive tools for software development teams. Combining project management, issue tracking, source control management, continuous integration, and document management into a unified platform, Tuleap helps teams collaborate efficiently from planning to deployment.

Built with PHP and backed by MySQL, Tuleap offers enterprise-grade features comparable to commercial ALM solutions. It supports agile methodologies including Scrum and Kanban, integrates with Git and SVN repositories, and provides extensive customization options for workflows and trackers.

Key highlights of Tuleap:

• Agile Project Management: Scrum and Kanban boards with sprint planning
• Issue Tracking: Customizable trackers for bugs, tasks, requirements, and more
• Source Control: Native Git and SVN integration with code review
• CI/CD Integration: Connect with Jenkins, GitLab CI, and other tools
• Document Management: Centralized document storage with versioning
• Wiki: Collaborative documentation with rich editing
• Test Management: Test cases, campaigns, and execution tracking
• Baseline Comparison: Compare project states over time
• Reporting: Customizable charts and dashboards
• REST API: Full API for automation and integration
• Open Source: Licensed under GPL v2

This guide walks through deploying Tuleap on Klutch.sh using Docker, configuring persistent storage, and setting up your development platform.

Why Deploy Tuleap on Klutch.sh

Deploying Tuleap on Klutch.sh provides several advantages for development teams:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Tuleap without complex server configuration. Push to GitHub, and your ALM platform deploys automatically.

Persistent Storage: Attach persistent volumes for your project data, repositories, and documents. Your development artifacts survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your development platform and Git repositories.

Scalable Resources: Allocate CPU and memory based on your team size and project complexity. Start small and scale as your organization grows.

Always-On Availability: Your development platform remains accessible 24/7 from anywhere in the world.

Prerequisites

Before deploying Tuleap on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Tuleap configuration
• Basic familiarity with Docker and ALM concepts
• A MySQL/MariaDB database (can be deployed separately on Klutch.sh)
• (Optional) A custom domain for your Tuleap instance

Understanding Tuleap Architecture

Tuleap is built on a comprehensive stack:

PHP Application: The core application handling web interface and business logic.

MySQL Database: Stores all project data, user information, and configuration.

Git/SVN Repositories: Version control repositories hosted within Tuleap.

File Storage: Documents, attachments, and artifacts stored on disk.

Background Workers: Handle asynchronous tasks like notifications and system events.

Preparing Your Repository

To deploy Tuleap on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

tuleap-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM tuleap/tuleap-community-edition:latest

# Set environment variables
ENV TULEAP_FQDN=${TULEAP_FQDN}
ENV DB_HOST=${DB_HOST}
ENV DB_USER=${DB_USER}
ENV DB_PASSWORD=${DB_PASSWORD}
ENV DB_NAME=${DB_NAME:-tuleap}
ENV SITE_ADMINISTRATOR_PASSWORD=${SITE_ADMINISTRATOR_PASSWORD}

# Create necessary directories
RUN mkdir -p /data

# Expose ports
EXPOSE 80 443 22

# Health check
HEALTHCHECK --interval=60s --timeout=10s --start-period=300s --retries=3 \
  CMD curl -f http://localhost/api/version || exit 1

Environment Variables Reference

Variable	Required	Default	Description
TULEAP_FQDN	Yes	-	Fully qualified domain name for your Tuleap instance
DB_HOST	Yes	-	MySQL server hostname
DB_USER	Yes	-	MySQL username
DB_PASSWORD	Yes	-	MySQL password
DB_NAME	No	tuleap	Database name
SITE_ADMINISTRATOR_PASSWORD	Yes	-	Password for the site admin account

Deploying Tuleap on Klutch.sh

Once your repository is prepared, follow these steps to deploy Tuleap:

Set Up a MySQL Database

Tuleap requires a MySQL database. Deploy one on Klutch.sh or use a managed MySQL service:

1. Create a database named tuleap
2. Create a user with full privileges on that database
3. Note the connection details

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Tuleap deployment configuration"
git remote add origin https://github.com/yourusername/tuleap-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “tuleap” or “dev-platform”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Tuleap Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 443 (Tuleap default HTTPS port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
TULEAP_FQDN	your-app-name.klutch.sh
DB_HOST	Your MySQL host
DB_USER	Your MySQL username
DB_PASSWORD	Your MySQL password
DB_NAME	tuleap
SITE_ADMINISTRATOR_PASSWORD	A secure admin password

Attach Persistent Volumes

Persistent storage is essential for Tuleap. Add the following volumes:

Mount Path	Recommended Size	Purpose
/data	50+ GB	All Tuleap data including repositories, documents, and uploads

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Tuleap container
• Provision an HTTPS certificate

Access Tuleap

Once deployment completes (initial setup may take several minutes), access your Tuleap instance at https://your-app-name.klutch.sh. Log in with username admin and the password you configured.

Initial Setup and Configuration

First Login

When you first access Tuleap:

1. Log in as admin with your configured password
2. Complete any first-run configuration wizards
3. Set up your organization details

Creating Projects

Create your first project:

1. Click “Create a new project”
2. Choose a template (Scrum, Kanban, empty)
3. Enter project name and details
4. Select services to enable
5. Configure access permissions

Project Services

Enable services based on your needs:

• Trackers: Bug tracking, task management, requirements
• Git: Source code repositories
• Agile Dashboard: Scrum/Kanban boards
• Documents: Document management
• Wiki: Collaborative documentation
• File Releases: Software release distribution

Tracker Configuration

Creating Trackers

Set up custom trackers for your workflow:

1. Navigate to project administration
2. Go to Trackers
3. Create new tracker from scratch or template
4. Define fields and workflow states

Field Types

Available field types include:

• Text fields (single line, multi-line)
• Select boxes (single, multi-select)
• Date pickers
• Numeric fields
• File attachments
• Cross-references to other trackers
• Computed fields

Workflow Configuration

Define state transitions:

1. Create workflow states (e.g., New, In Progress, Resolved)
2. Define allowed transitions between states
3. Set field requirements for each transition
4. Configure notifications

Agile Features

Scrum Configuration

Set up Scrum for your team:

1. Enable Agile Dashboard in project services
2. Configure the backlog tracker
3. Set up sprint tracker
4. Define story point field
5. Create sprints and add stories

Kanban Boards

Configure Kanban workflow:

1. Create a Kanban board
2. Map tracker states to columns
3. Set WIP limits
4. Enable swimlanes if needed

Burndown Charts

Track progress with built-in charts:

• Burndown/burnup charts
• Velocity tracking
• Cumulative flow diagrams

Git Integration

Creating Repositories

Set up Git repositories:

1. Enable Git in project services
2. Create new repository
3. Clone URL is automatically generated
4. Push code using SSH or HTTPS

Code Review

Use Tuleap for code review:

1. Create pull requests from branches
2. Assign reviewers
3. Inline code comments
4. Approve or request changes

Access Control

Configure repository permissions:

• Read/write access by user or group
• Branch-level permissions
• Protected branches

User Management

Creating Users

Add users to your Tuleap instance:

1. Go to Site Administration > Users
2. Create new user accounts
3. Set initial passwords
4. Assign to user groups

User Groups

Organize users into groups:

• Project-level groups for access control
• Global groups for site-wide permissions

LDAP Integration

Connect to enterprise directory:

1. Configure LDAP settings in site administration
2. Map LDAP groups to Tuleap groups
3. Enable LDAP authentication

Production Best Practices

Security Recommendations

• Strong Passwords: Enforce password policies
• HTTPS Only: Klutch.sh provides this automatically
• Access Control: Implement least-privilege access
• Regular Updates: Keep Tuleap updated for security patches

Backup Strategy

Protect your development data:

1. Database Backups: Regular MySQL backups
2. File Storage: Back up /data directory
3. Git Repositories: Repositories are part of file storage
4. Test Restores: Regularly verify backup integrity

Performance Optimization

• Database Tuning: Optimize MySQL for your workload
• Resource Allocation: Scale based on user count
• Cache Configuration: Enable appropriate caching

Troubleshooting Common Issues

Installation Hangs

Symptoms: First startup takes too long or hangs.

Solutions:

• Check database connectivity
• Verify sufficient resources allocated
• Review container logs for errors

Git Access Issues

Symptoms: Cannot clone or push to repositories.

Solutions:

• Verify TULEAP_FQDN is correct
• Check SSH key configuration
• Verify user permissions

Performance Problems

Symptoms: Slow page loads or timeouts.

Solutions:

• Check database performance
• Increase server resources
• Review slow query logs

Additional Resources

• Tuleap Official Website
• Tuleap Documentation
• Tuleap GitHub Repository
• Tuleap Community
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Tuleap on Klutch.sh gives you a comprehensive application lifecycle management platform accessible from anywhere. The combination of Tuleap’s enterprise features and Klutch.sh’s deployment simplicity means you can focus on development rather than infrastructure.

With integrated project management, issue tracking, source control, and CI/CD capabilities, Tuleap provides everything your development team needs in a single platform. Your code, documentation, and project artifacts remain under your control in a secure, always-available environment.