Deploying Kallithea

Introduction

Kallithea is a self-hosted source code management system that supports both Git and Mercurial repositories. Forked from RhodeCode, Kallithea provides a unified platform for hosting, browsing, and managing your code repositories with built-in code review, pull requests, and team collaboration features.

Written in Python using the Pylons/Pyramid framework, Kallithea offers a polished web interface for repository management, user administration, and code review workflows. The dual VCS support makes it ideal for teams working with both Git and Mercurial projects.

Key highlights of Kallithea:

Dual VCS Support: Host both Git and Mercurial repositories in a single installation
Code Review: Built-in pull request system with inline commenting and approval workflows
Repository Browsing: Full-featured web interface for browsing code, history, and diffs
User Management: LDAP/Active Directory integration, user groups, and fine-grained permissions
Repository Groups: Organize repositories into hierarchical groups
Gist Support: Create and share code snippets with syntax highlighting
API Access: REST API for automation and integration
Hooks System: Extensible hooks for custom integrations
Full-Text Search: Search across all repositories with advanced filtering
Activity Feeds: Track repository activity and user contributions
Open Source: GPLv3 licensed with an active community

This guide walks through deploying Kallithea on Klutch.sh using Docker, configuring repositories, and setting up the application for team use.

Why Deploy Kallithea on Klutch.sh

Deploying Kallithea on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kallithea without complex configuration.

Persistent Storage: Attach persistent volumes for your repositories and database. Your code and configuration survive restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Scalable Resources: Allocate CPU and memory based on repository size and team activity.

Environment Variable Management: Securely store database credentials and secret keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Kallithea instance for professional repository hosting.

Always-On Availability: Your repositories remain accessible 24/7.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Kallithea configuration
Basic familiarity with Docker and containerization concepts
Understanding of Git and/or Mercurial version control
(Optional) A custom domain for your Kallithea instance

Understanding Kallithea Architecture

Kallithea uses a straightforward architecture:

Web Application: The Pyramid-based web application handles HTTP requests, repository browsing, and the user interface.

VCS Backends: Git and Mercurial backends provide repository operations through their respective libraries.

Database: SQLite, PostgreSQL, or MySQL stores users, permissions, pull requests, and metadata.

File Storage: Repositories are stored as standard Git and Mercurial repositories on the filesystem.

Whoosh Index: Full-text search index for code searching across repositories.

Preparing Your Repository

To deploy Kallithea on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

kallithea-deploy/
├── Dockerfile
├── kallithea.ini
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM python:3.9-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    mercurial \
    libffi-dev \
    libssl-dev \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Kallithea
RUN pip install kallithea

# Create directories
RUN mkdir -p /var/lib/kallithea/repos /var/lib/kallithea/data

# Set working directory
WORKDIR /var/lib/kallithea

# Copy configuration
COPY kallithea.ini /var/lib/kallithea/kallithea.ini

# Initialize database (first run)
RUN kallithea-cli db-create -c kallithea.ini --user admin --password ${ADMIN_PASSWORD:-admin} --email admin@example.com --repos /var/lib/kallithea/repos

# Expose web interface
EXPOSE 5000

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

CMD ["kallithea-cli", "serve", "-c", "kallithea.ini"]

Configuration File

Create a kallithea.ini configuration file:

[DEFAULT]
debug = false

[server:main]
use = egg:waitress#main
host = 0.0.0.0
port = 5000
threads = 4

[app:main]
use = egg:kallithea

# Instance settings
instance_id = production
app_instance_uuid = ${APP_INSTANCE_UUID}

# Paths
repo_store.path = /var/lib/kallithea/repos
cache_dir = /var/lib/kallithea/data/cache
index_dir = /var/lib/kallithea/data/index

# Database - SQLite for simplicity
sqlalchemy.db1.url = sqlite:///var/lib/kallithea/data/kallithea.db

# Security
cookie_secret = ${COOKIE_SECRET}
beaker.session.secret = ${SESSION_SECRET}

# Email settings
email_to = admin@example.com
smtp_server = localhost

# Repository settings
default_repo_enable_locking = false
default_repo_enable_downloads = true
default_repo_enable_statistics = true

# SSH settings (optional)
ssh_enabled = false

# Logging
[loggers]
keys = root, kallithea

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = WARNING
handlers = console

[logger_kallithea]
level = INFO
handlers =
qualname = kallithea

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(asctime)s %(levelname)-5.5s [%(name)s] %(message)s

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
`ADMIN_PASSWORD`	Yes	-	Initial admin user password
`COOKIE_SECRET`	Yes	-	Secret for cookie encryption
`SESSION_SECRET`	Yes	-	Secret for session management
`APP_INSTANCE_UUID`	No	-	Unique instance identifier

Deploying Kallithea on Klutch.sh

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

Generate Secure Secrets

Generate secrets for your configuration:

python -c "import secrets; print(secrets.token_hex(32))"  # For COOKIE_SECRET
python -c "import secrets; print(secrets.token_hex(32))"  # For SESSION_SECRET

Save these securely for environment variable configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile kallithea.ini .dockerignore README.md
git commit -m "Initial Kallithea deployment configuration"
git remote add origin https://github.com/yourusername/kallithea-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 “kallithea” or “source-code”.

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 Kallithea Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 5000

Set Environment Variables

In the environment variables section, add:

Variable	Value
`ADMIN_PASSWORD`	Your secure admin password
`COOKIE_SECRET`	Your generated cookie secret
`SESSION_SECRET`	Your generated session secret

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/lib/kallithea/repos`	50+ GB	Git and Mercurial repositories
`/var/lib/kallithea/data`	5 GB	Database, cache, and search index

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 Kallithea container
Provision an HTTPS certificate

Access Kallithea

Once deployment completes, access your Kallithea instance at https://example-app.klutch.sh. Log in with the admin credentials you configured.

Initial Setup and Configuration

Creating Repositories

After logging in as admin:

Click Add Repository in the navigation
Choose repository type (Git or Mercurial)
Enter repository name and description
Select repository group (optional)
Configure visibility and permissions
Click Create

Repository Groups

Organize repositories into groups:

Navigate to Admin > Repository Groups
Click Add Group
Enter group name and description
Set default permissions for the group
Create subgroups for hierarchical organization

User Management

Add team members:

Go to Admin > Users
Click Add User
Enter username, email, and password
Assign to user groups if needed
Set default permissions

LDAP/Active Directory

For enterprise authentication:

Navigate to Admin > Authentication
Enable LDAP authentication
Configure LDAP server settings
Map LDAP groups to Kallithea groups
Test the connection

Working with Repositories

Cloning Repositories

Clone over HTTPS:

git clone https://example-app.klutch.sh/username/repository.git

For Mercurial:

hg clone https://example-app.klutch.sh/username/repository

Pull Requests

Create and review pull requests:

Push your feature branch
Navigate to the repository
Click Create Pull Request
Select source and target branches
Add description and reviewers
Submit for review

Code Review

Review code changes:

Open a pull request
Browse the diff view
Add inline comments on specific lines
Submit overall review with approval or changes requested
Merge when approved

Production Best Practices

Security Recommendations

Strong Passwords: Enforce strong passwords for all users
HTTPS Only: Always access Kallithea over HTTPS
Permission Auditing: Regularly review repository permissions
API Token Security: Protect API tokens like passwords
Update Regularly: Keep Kallithea updated for security patches

Performance Optimization

Repository Caching: Enable repository caching for frequently accessed repos
Search Indexing: Schedule index updates during off-peak hours
Database Optimization: Consider PostgreSQL for larger installations
Resource Allocation: Scale resources based on repository count and team size

Backup Strategy

Protect your repositories:

Repository Backups: Regularly back up /var/lib/kallithea/repos
Database Backups: Back up the SQLite or PostgreSQL database
Configuration Backups: Version control your kallithea.ini
Offsite Storage: Store backups in a separate location

Troubleshooting Common Issues

Repository Operations Failing

Symptoms: Push, pull, or clone operations fail.

Solutions:

Check repository permissions for the user
Verify disk space availability
Review Kallithea logs for specific errors
Ensure Git/Mercurial client versions are compatible

Authentication Problems

Symptoms: Cannot log in or LDAP not working.

Solutions:

Verify user credentials
Check LDAP configuration settings
Review authentication logs
Test LDAP connection separately

Search Not Working

Symptoms: Code search returns no results.

Solutions:

Rebuild the search index
Check index directory permissions
Verify Whoosh is properly installed
Review indexing logs for errors

Additional Resources

Conclusion

Deploying Kallithea on Klutch.sh gives you a powerful, self-hosted source code management system with support for both Git and Mercurial. The combination of Kallithea’s comprehensive features and Klutch.sh’s deployment simplicity means you can focus on your code rather than infrastructure.

With built-in code review, pull requests, and team collaboration features, Kallithea provides everything needed for professional software development. Whether you’re a small team or a larger organization, Kallithea on Klutch.sh offers a reliable, always-available platform for hosting and collaborating on your code.