Deploying minimal-git-server

Introduction

minimal-git-server is a stripped-down Git server that provides essential Git hosting functionality without the overhead of full-featured platforms like GitLab or Gitea. It’s perfect for personal projects, small teams, or situations where you need simple, reliable Git hosting.

Unlike comprehensive Git platforms, minimal-git-server focuses solely on Git operations. There’s no web interface for browsing code, no issue tracking, no CI/CD—just pure Git push and pull functionality over HTTP or SSH.

Key highlights of minimal-git-server:

• Lightweight: Minimal resource usage and fast startup
• Simple Setup: No complex configuration required
• HTTP Support: Clone and push over HTTP/HTTPS
• SSH Support: Secure access via SSH keys
• No Dependencies: Runs with just Git and a web server
• Docker Ready: Easy containerized deployment
• Multi-Repository: Host unlimited repositories
• Authentication: Basic HTTP auth or SSH keys
• Hooks Support: Standard Git hooks for automation
• 100% Open Source: Simple, auditable codebase

This guide walks through deploying minimal-git-server on Klutch.sh using Docker, creating repositories, and configuring Git access.

Why Deploy minimal-git-server on Klutch.sh

Deploying minimal-git-server on Klutch.sh provides several advantages:

Private Repositories: Host unlimited private repos without GitHub limits.

Simplified Deployment: Klutch.sh handles container deployment automatically.

Persistent Storage: Repositories survive restarts and redeployments.

HTTPS by Default: Secure Git operations with automatic SSL.

Low Resource Usage: Minimal overhead means lower costs.

Data Ownership: Complete control over your code.

Prerequisites

Before deploying minimal-git-server 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
• SSH key pair for Git access (optional)

Understanding minimal-git-server Architecture

The architecture is intentionally simple:

Git Backend: Standard Git binaries handling repository operations.

HTTP Server: Serves Git Smart HTTP protocol for cloning and pushing.

SSH Server: Optional SSH access for key-based authentication.

File System: Bare Git repositories stored on disk.

Preparing Your Repository

Create a GitHub repository for your minimal-git-server deployment.

Repository Structure

minimal-git-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM alpine:latest

# Install Git and nginx for Smart HTTP
RUN apk add --no-cache \
    git \
    git-daemon \
    nginx \
    fcgiwrap \
    spawn-fcgi \
    openssh

# Set up Git HTTP backend
RUN mkdir -p /var/lib/git /run/nginx

# Configure nginx for git-http-backend
COPY <<'EOF' /etc/nginx/http.d/git.conf
server {
    listen 80 default_server;
    root /var/lib/git;

    location ~ (/.*) {
        client_max_body_size 0;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /usr/libexec/git-core/git-http-backend;
        fastcgi_param GIT_HTTP_EXPORT_ALL "";
        fastcgi_param GIT_PROJECT_ROOT /var/lib/git;
        fastcgi_param PATH_INFO $1;
        fastcgi_param REMOTE_USER $remote_user;
        fastcgi_pass unix:/var/run/fcgiwrap.socket;
    }
}
EOF

# Create startup script
COPY <<'EOF' /start.sh
#!/bin/sh
spawn-fcgi -s /var/run/fcgiwrap.socket -u nginx -g nginx /usr/bin/fcgiwrap
chmod 777 /var/run/fcgiwrap.socket
nginx -g 'daemon off;'
EOF

RUN chmod +x /start.sh

# Expose HTTP port
EXPOSE 80

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

CMD ["/start.sh"]

Dockerfile with Authentication

For password-protected repositories:

FROM alpine:latest

# Install packages
RUN apk add --no-cache \
    git \
    git-daemon \
    nginx \
    fcgiwrap \
    spawn-fcgi \
    apache2-utils

# Set up directories
RUN mkdir -p /var/lib/git /run/nginx

# Create password file (will be populated via env)
RUN touch /etc/nginx/.htpasswd

# Configure nginx with basic auth
COPY <<'EOF' /etc/nginx/http.d/git.conf
server {
    listen 80 default_server;
    root /var/lib/git;

    auth_basic "Git Repository";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location ~ (/.*) {
        client_max_body_size 0;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME /usr/libexec/git-core/git-http-backend;
        fastcgi_param GIT_HTTP_EXPORT_ALL "";
        fastcgi_param GIT_PROJECT_ROOT /var/lib/git;
        fastcgi_param PATH_INFO $1;
        fastcgi_param REMOTE_USER $remote_user;
        fastcgi_pass unix:/var/run/fcgiwrap.socket;
    }
}
EOF

# Create startup script
COPY <<'EOF' /start.sh
#!/bin/sh
# Set up authentication if credentials provided
if [ -n "$GIT_USER" ] && [ -n "$GIT_PASSWORD" ]; then
    htpasswd -bc /etc/nginx/.htpasswd "$GIT_USER" "$GIT_PASSWORD"
fi

spawn-fcgi -s /var/run/fcgiwrap.socket -u nginx -g nginx /usr/bin/fcgiwrap
chmod 777 /var/run/fcgiwrap.socket
nginx -g 'daemon off;'
EOF

RUN chmod +x /start.sh

EXPOSE 80

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

CMD ["/start.sh"]

Environment Variables Reference

Variable	Required	Default	Description
GIT_USER	No	-	Username for HTTP authentication
GIT_PASSWORD	No	-	Password for HTTP authentication

Deploying minimal-git-server on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository:

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

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables (if using authentication)

Add the following environment variables:

Variable	Value
GIT_USER	Your Git username
GIT_PASSWORD	Your secure password

Attach Persistent Volumes

Add storage for your repositories:

Mount Path	Recommended Size	Purpose
/var/lib/git	10+ GB	Git repository storage

Deploy Your Application

Click Deploy to start the build process.

Access minimal-git-server

Once deployed, your Git server is available at https://your-app-name.klutch.sh.

Creating Repositories

Creating a New Repository

Create a bare repository on the server:

1. Access the container terminal
2. Run:

cd /var/lib/git
git init --bare myproject.git

Initializing Repository from Local

Push an existing local repository:

# In your local project
git remote add origin https://your-app-name.klutch.sh/myproject.git
git push -u origin main

Cloning Repositories

Clone from your Git server:

git clone https://your-app-name.klutch.sh/myproject.git

With authentication:

git clone https://username@your-app-name.klutch.sh/myproject.git

Git Operations

Pushing Changes

Push commits as usual:

git add .
git commit -m "Your message"
git push origin main

Pulling Changes

Pull updates from the server:

git pull origin main

Working with Branches

Full branch support:

git checkout -b feature-branch
git push -u origin feature-branch

Repository Management

Listing Repositories

View all repositories:

ls /var/lib/git

Deleting Repositories

Remove a repository:

rm -rf /var/lib/git/myproject.git

Repository Hooks

Add automation with Git hooks:

# Create post-receive hook
cat > /var/lib/git/myproject.git/hooks/post-receive << 'EOF'
#!/bin/sh
echo "Push received!"
# Add your automation here
EOF
chmod +x /var/lib/git/myproject.git/hooks/post-receive

Backup Strategy

Backing Up Repositories

Export repositories for backup:

# Clone with mirror for complete backup
git clone --mirror /var/lib/git/myproject.git backup/myproject.git

Restoring from Backup

Restore a repository:

cp -r backup/myproject.git /var/lib/git/myproject.git

Security Considerations

Credential Management

For authenticated setups:

• Use strong, unique passwords
• Consider credential managers for convenience
• Rotate passwords periodically

Access Control

This minimal server has simple access control:

• All authenticated users have full access
• Use separate instances for different access levels
• Consider firewall rules for additional security

Troubleshooting

Authentication Failures

• Verify username and password
• Check that credentials are URL-encoded if special characters
• Review nginx error logs

Push Rejected

• Ensure repository exists
• Check file permissions
• Verify receive-pack is enabled

Clone Failures

• Confirm repository path is correct
• Check authentication credentials
• Verify network connectivity

Additional Resources

• Git Server Setup Guide
• git-http-backend Documentation
• Git Hooks Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying minimal-git-server on Klutch.sh gives you a simple, lightweight Git hosting solution for private repositories. Without the overhead of full-featured platforms, you get pure Git functionality with minimal resource usage.

Host your code privately and simply with minimal-git-server on Klutch.sh.