Configure Git Webserver

Overview

This skill provides guidance for setting up a Git-based web deployment system where pushing to a Git repository automatically deploys content to a web server. The typical workflow involves creating a bare Git repository, configuring a post-receive hook to deploy content, and running a web server to serve the deployed files.

Approach

Component Identification

Before implementation, identify all required components:

• Bare Git repository - The central repository that receives pushes

• Web content directory - Where deployed files are served from

• Post-receive hook - Automates deployment on push

• Web server - Serves the deployed content

• User access - Permissions for users to push to the repository

Implementation Sequence

Execute tasks in dependency order:

• Create the bare Git repository first (other components depend on its location)

• Create the web content directory

• Create and configure the post-receive hook (depends on both repository and web directory)

• Start the web server (depends on web directory existing)

• Configure user access as needed

Post-Receive Hook Design

The post-receive hook should:

• Handle multiple branch names (both master and main for compatibility)

• Use git --work-tree to checkout to the web directory

• Be marked executable (chmod +x )

• Include the proper shebang (#!/bin/bash )

Example hook structure:

#!/bin/bash while read oldrev newrev ref do branch=$(echo $ref | cut -d/ -f3) if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then git --work-tree=/path/to/web/dir --git-dir=/path/to/repo checkout -f $branch fi done

Web Server Options

Consider available options based on environment:

• python3 -m http.server

• Simple, usually available, single-threaded

• nginx

• Production-ready, requires installation

• node http-server

• Requires Node.js

• busybox httpd

• Lightweight, often available in minimal environments

Verification Strategies

Component-Level Verification

Verify each component independently before testing the full workflow:

Repository verification: Check that the bare repository exists and has correct structure

ls -la /path/to/repo # Should show HEAD, objects/, refs/, etc.

Hook verification: Confirm hook exists and is executable

ls -la /path/to/repo/hooks/post-receive

Web server verification: Confirm server is running and listening

ss -tlnp | grep :PORT # or netstat -tlnp, or ps aux | grep server

End-to-End Testing

Test the complete workflow:

• Clone the repository (use local path for initial testing)

• Create a test file and commit

• Push to the repository

• Verify the file appears in the web directory

• Verify the file is accessible via HTTP

Pre-Check Available Commands

Before using system commands, verify availability to reduce trial-and-error:

command -v netstat || command -v ss # Network status command -v systemctl || command -v service # Service management

Common Pitfalls

Persistence Issues

Problem: Background processes (like python3 -m http.server & ) do not survive system restarts.

Mitigation: For production use, create a systemd service or use a process manager. For testing purposes, background processes are acceptable but document the limitation.

Permission Issues

Problem: Users cannot push to the repository or the hook cannot write to the web directory.

Mitigation:

• Verify repository ownership and permissions

• Ensure the user running the hook has write access to the web directory

• Check that the hook itself is executable

Branch Name Handling

Problem: Hook only handles master but user pushes to main (or vice versa).

Mitigation: Handle both common default branch names in the hook logic.

Testing Methodology

Problem: Testing with local paths (/git/server ) may pass but SSH-based access (user@server:/git/server ) may fail.

Mitigation: If SSH access is required, verify SSH configuration and user access separately from the Git/web functionality.

Error Handling in Hooks

Problem: Hook failures are silent, making debugging difficult.

Mitigation: Add error output and logging to hooks:

exec 2>&1 # Redirect stderr to stdout set -e # Exit on error

Single-Threaded Web Servers

Problem: Simple web servers like python3 -m http.server are single-threaded and unsuitable for concurrent access.

Mitigation: Document this limitation. For production, use a proper web server like nginx.

Task Breakdown Guidance

Avoid excessive granularity in task tracking. Group related operations:

• Good: "Set up bare Git repository with post-receive hook"

• Avoid: Separate tasks for "create directory", "run git init", "create hook file", "make hook executable"

Focus task tracking on logical milestones rather than individual commands.