Deploying rgit

Introduction

rgit is an ultrafast Git repository browser written in Rust, designed to provide a simple, fast web interface for browsing Git repositories. Unlike full-featured forges like GitLab or Gitea, rgit focuses purely on repository browsing with minimal overhead and maximum performance.

Built for speed and simplicity, rgit leverages Rust’s performance characteristics to deliver instant page loads even for large repositories. It’s ideal for self-hosting when you need a lightweight way to share and browse code without the complexity of a full Git hosting platform.

Key highlights of rgit:

• Blazing Fast: Written in Rust for maximum performance
• Minimal Resource Usage: Low memory and CPU footprint
• Clean Interface: Simple, functional design focused on code browsing
• Syntax Highlighting: Code highlighting for many languages
• Commit History: Browse commits, diffs, and file history
• Branch/Tag Support: View different branches and tagged releases
• File Browser: Navigate repository file trees
• README Rendering: Automatic Markdown rendering for README files
• Raw File Access: Download raw files directly
• No Database Required: Works directly with Git repositories
• Multi-Repository: Browse multiple repositories from one installation
• Open Source: Licensed under WTFPL

This guide walks through deploying rgit on Klutch.sh using Docker, configuring it to browse your Git repositories, and setting up the application for production use.

Why Deploy rgit on Klutch.sh

Deploying rgit on Klutch.sh provides several advantages for repository browsing:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds rgit without complex orchestration. Push to GitHub, and your repository browser deploys automatically.

Persistent Storage: Attach persistent volumes for your Git repositories. Your repository data persists across container restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: rgit is extremely lightweight, making it efficient even on minimal resources.

Custom Domains: Assign a custom domain to your rgit instance for professional repository URLs.

Always-On Availability: Your repository browser runs 24/7, providing constant access to your codebase.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your rgit configuration
• Basic familiarity with Docker and Git concepts
• Git repositories you want to browse (bare or regular)
• (Optional) A custom domain for your rgit instance

Understanding rgit Architecture

rgit is designed for simplicity:

Rust Binary: A single compiled binary handles all functionality including HTTP serving, Git operations, and HTML rendering.

Direct Git Access: rgit reads directly from Git repositories using libgit2, requiring no database or external services.

Static Templates: HTML templates are compiled into the binary for fast rendering.

Repository Scanning: On startup, rgit scans configured directories for Git repositories and monitors for changes.

Stateless Operation: No session state or user accounts - purely read-only browsing.

Preparing Your Repository

To deploy rgit on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

rgit-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM rust:1.75-alpine AS builder

# Install build dependencies
RUN apk add --no-cache musl-dev git libgit2-dev

# Clone and build rgit
WORKDIR /build
RUN git clone https://github.com/w4/rgit.git . && \
    cargo build --release

FROM alpine:latest

# Install runtime dependencies
RUN apk add --no-cache libgit2 git

# Copy the binary
COPY --from=builder /build/target/release/rgit /usr/local/bin/rgit

# Create directories
RUN mkdir -p /repos

# Environment variables
ENV RGIT_BIND_ADDRESS=0.0.0.0:8080
ENV RGIT_REPOSITORY_DIR=/repos

# Expose the web port
EXPOSE 8080

CMD ["rgit"]

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
RGIT_BIND_ADDRESS	No	0.0.0.0:8080	Address and port to bind
RGIT_REPOSITORY_DIR	Yes	-	Directory containing Git repositories
RGIT_CACHE_DIR	No	-	Directory for caching rendered content

Deploying rgit on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

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

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
RGIT_BIND_ADDRESS	0.0.0.0:8080
RGIT_REPOSITORY_DIR	/repos

Attach Persistent Volumes

Add the following volumes for data persistence:

Mount Path	Recommended Size	Purpose
/repos	50+ GB	Git repositories to browse

Deploy Your Application

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

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

Add Repositories

After deployment, add Git repositories to the /repos volume. rgit will automatically detect and index them.

Access rgit

Once deployment completes and repositories are added, access your rgit instance at https://your-app-name.klutch.sh.

Adding Repositories

Cloning Bare Repositories

For optimal performance, use bare repositories:

git clone --bare https://github.com/user/repo.git /repos/repo.git

Mirror Existing Repositories

To keep repositories in sync:

git clone --mirror https://github.com/user/repo.git /repos/repo.git

Repository Organization

Organize repositories in subdirectories for grouping:

/repos/
├── projects/
│   ├── project-a.git
│   └── project-b.git
├── libraries/
│   ├── lib-core.git
│   └── lib-utils.git
└── tools/
    └── internal-tool.git

rgit will display the directory structure in its interface.

Features and Usage

Browsing Repositories

The main page lists all discovered repositories with:

• Repository name and description
• Last commit information
• Quick links to branches and files

Viewing Commits

Click on a repository to see:

• Recent commit history
• Commit details with full diff
• Author and timestamp information

File Browsing

Navigate the file tree to:

• View source code with syntax highlighting
• See file history
• Download raw files
• View rendered Markdown files

Branch and Tag Navigation

Switch between:

• Different branches
• Tagged releases
• Specific commits

Production Best Practices

Security Recommendations

• Read-Only Access: rgit only provides read access - no push capabilities
• Repository Selection: Only include repositories you want publicly accessible
• Access Control: Use Klutch.sh networking options if private access is needed

Performance Optimization

• Bare Repositories: Use bare clones for better performance
• Repository Size: Very large repositories may need more resources
• Cache Directory: Configure a cache directory for faster repeated access

Backup Strategy

1. Repository Mirrors: Keep repositories synced with upstream sources
2. Volume Backups: Regularly back up the /repos volume

Troubleshooting Common Issues

Repositories Not Appearing

Symptoms: Added repositories don’t show in the interface.

Solutions:

• Verify repository path is within RGIT_REPOSITORY_DIR
• Check repository is a valid Git repository
• Ensure file permissions allow reading
• Restart rgit to trigger re-scan

Slow Page Loads

Symptoms: Pages load slowly for large repositories.

Solutions:

• Ensure sufficient memory allocation
• Use bare repositories
• Configure a cache directory
• Consider repository size limits

Syntax Highlighting Issues

Symptoms: Code appears without highlighting.

Solutions:

• Verify file extension is recognized
• Check for unusual file encodings
• Some languages may have limited support

Additional Resources

• rgit GitHub Repository
• rgit Demo Instance
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying rgit on Klutch.sh gives you an ultrafast, lightweight Git repository browser with automatic builds, persistent storage, and secure HTTPS access. The combination of rgit’s Rust-powered performance and Klutch.sh’s deployment simplicity means you can browse code instantly without heavy infrastructure.

With syntax highlighting, commit history, and file browsing, rgit provides everything needed for read-only repository access. The minimal resource requirements make it perfect for sharing code without the overhead of a full Git forge.

Whether you’re hosting documentation, sharing libraries, or providing public access to your projects, rgit on Klutch.sh delivers fast, reliable repository browsing.