Deploying GitBucket

Introduction

GitBucket is a self-hosted Git platform written in Scala that provides a GitHub-like experience for repository hosting, issue tracking, and code collaboration. It offers an easy way to set up a private Git server with a familiar web interface.

Built on the JVM, GitBucket is designed for simplicity and ease of installation. It works out of the box with an embedded H2 database but also supports PostgreSQL and MySQL for larger deployments. The platform includes most features developers expect from modern Git hosting.

Key highlights of GitBucket:

• GitHub-like Interface: Familiar UI for repository browsing and management
• Repository Hosting: Git repository hosting with SSH and HTTP access
• Issue Tracking: Full issue management with labels and milestones
• Pull Requests: Code review workflow with merge capabilities
• Wiki: Built-in wiki for each repository
• Repository Viewer: Syntax-highlighted code browsing
• Plugin System: Extend functionality with plugins
• API Compatibility: GitHub-compatible API for tool integration
• LDAP Support: Enterprise authentication integration
• Organization Support: Group repositories under organizations
• Easy Installation: Single JAR file with embedded server
• Open Source: Licensed under Apache 2.0

This guide walks through deploying GitBucket on Klutch.sh using Docker.

Why Deploy GitBucket on Klutch.sh

Deploying GitBucket on Klutch.sh provides several advantages:

Private Repository Hosting: Keep your code on infrastructure you control.

Remote Access: Access repositories from anywhere with internet connectivity.

Persistent Storage: Repositories and data survive container updates.

HTTPS by Default: Secure access to your Git server without certificate management.

Team Collaboration: Enable team access without complex networking.

Custom Domain: Use your own domain for professional repository URLs.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and Git
• (Optional) An external database for production use

Understanding GitBucket Architecture

GitBucket consists of:

Jetty Server: Embedded web server for HTTP requests.

Git Backend: JGit library for Git operations.

Database: H2 (embedded), PostgreSQL, or MySQL for metadata.

File Storage: Repositories stored on the file system.

Plugin System: Extensible architecture for additional features.

Preparing Your Repository

Create a GitHub repository with your GitBucket configuration.

Repository Structure

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

Creating the Dockerfile

FROM gitbucket/gitbucket:latest

# Set environment variables
ENV GITBUCKET_HOME=/gitbucket
ENV GITBUCKET_PORT=8080
ENV GITBUCKET_PREFIX=

# Create data directory
RUN mkdir -p /gitbucket

# Expose ports
EXPOSE 8080 29418

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

Advanced Dockerfile with PostgreSQL

For production deployments with PostgreSQL:

FROM gitbucket/gitbucket:latest

# Set environment variables
ENV GITBUCKET_HOME=/gitbucket
ENV GITBUCKET_PORT=8080
ENV GITBUCKET_DB_URL=${DB_URL}
ENV GITBUCKET_DB_USER=${DB_USER}
ENV GITBUCKET_DB_PASSWORD=${DB_PASSWORD}

# Create directories
RUN mkdir -p /gitbucket /gitbucket/repositories

EXPOSE 8080 29418

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/ || exit 1

Environment Variables Reference

Variable	Required	Description
GITBUCKET_HOME	No	Data directory (default: ~/.gitbucket)
GITBUCKET_PORT	No	HTTP port (default: 8080)
GITBUCKET_PREFIX	No	Context path prefix
GITBUCKET_DB_URL	No	JDBC database URL
GITBUCKET_DB_USER	No	Database username
GITBUCKET_DB_PASSWORD	No	Database password

Deploying GitBucket on Klutch.sh

Push Your Repository to GitHub

Commit your Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “gitbucket” or “git-server”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP traffic:

• Select HTTP as the traffic type
• Set the internal port to 8080

Attach Persistent Volumes

Mount Path	Size	Purpose
/gitbucket	50+ GB	Repositories and application data

Deploy Your Application

Click Deploy to build and launch GitBucket.

Complete Initial Setup

Access your GitBucket instance. Default admin credentials:

• Username: root
• Password: root

Change the default password immediately.

Initial Configuration

System Settings

1. Log in as root
2. Go to System Administration
3. Configure:
   • Base URL
   • SSH access
   • Account registration policy
   • Default visibility

Creating Users

1. Navigate to Administration > Users
2. Click “New User”
3. Fill in user details
4. Set permissions (Admin or Normal)

Creating Organizations

Organizations group repositories and teams:

1. Go to New > Organization
2. Set organization name
3. Add members and set roles

Repository Management

Creating Repositories

1. Click “New repository”
2. Choose owner (user or organization)
3. Set name and description
4. Choose visibility (public/private)
5. Initialize with README (optional)

Cloning Repositories

Clone via HTTPS:

git clone https://your-app.klutch.sh/user/repo.git

Push Existing Repository

git remote add origin https://your-app.klutch.sh/user/repo.git
git push -u origin main

Issue Tracking

Creating Issues

1. Navigate to repository
2. Click “Issues” tab
3. Click “New Issue”
4. Set title, description, and labels
5. Assign to team members

Labels and Milestones

Organize issues with:

• Custom labels (bug, feature, etc.)
• Milestones for release planning
• Assignees for work distribution

Pull Requests

Creating Pull Requests

1. Create a branch with changes
2. Push to GitBucket
3. Click “New Pull Request”
4. Select source and target branches
5. Add description and reviewers

Code Review

• Comment on specific lines
• Request changes or approve
• Merge when approved

Wiki

Each repository includes a wiki:

1. Click “Wiki” tab
2. Create pages with Markdown
3. Organize with page hierarchy
4. Track page history

Plugin System

Extend GitBucket with plugins:

Popular Plugins

• CI Plugin: Continuous integration
• Emoji Plugin: GitHub-style emoji support
• Notifications: Slack, email notifications
• Metrics: Repository statistics

Installing Plugins

1. Download plugin JAR file
2. Place in /gitbucket/plugins/
3. Restart GitBucket

API Access

GitBucket provides a GitHub-compatible API:

Authentication

Use personal access tokens:

1. Go to Account Settings
2. Generate access token
3. Use in API requests

API Endpoints

# List repositories
curl -H "Authorization: token YOUR_TOKEN" \
  https://your-app.klutch.sh/api/v3/user/repos

# Create repository
curl -X POST -H "Authorization: token YOUR_TOKEN" \
  -d '{"name":"new-repo"}' \
  https://your-app.klutch.sh/api/v3/user/repos

LDAP Integration

Connect to enterprise directory:

1. Go to System Administration
2. Configure LDAP settings:
   • Server URL
   • Base DN
   • Bind credentials
3. Test connection
4. Enable LDAP authentication

Backup and Recovery

Backup Strategy

Regular backups should include:

• /gitbucket/repositories/ - Git repositories
• /gitbucket/data/ - Database and configuration
• /gitbucket/plugins/ - Installed plugins

Database Backup

For PostgreSQL backends, use pg_dump for database backups.

Troubleshooting

Cannot Push/Pull

• Verify authentication credentials
• Check repository permissions
• Review Git server logs

Slow Performance

• Consider external database
• Increase JVM memory
• Review repository sizes

Login Issues

• Verify credentials
• Check LDAP configuration
• Review authentication logs

Additional Resources

• GitBucket Official Website
• GitBucket GitHub Repository
• GitBucket Documentation
• GitBucket Plugins

Conclusion

Deploying GitBucket on Klutch.sh provides a complete Git hosting solution with a familiar GitHub-like interface. Whether you need private repository hosting for your team or an alternative to cloud-based Git services, GitBucket offers essential features without complexity.

The combination of GitBucket’s ease of use and Klutch.sh’s reliable hosting creates an ideal platform for self-hosted Git collaboration.