gitserver

README

caddy-git-server

Provides a git_server caddy module for serving git repositories.

This module implements the necessary git http transfer protocols to serve clone-able git repositories. This allows you to self host your code with a simple caddy server + config.

Installation

You must build a custom version of caddy to use this module. Luckily, the xcaddy command makes this easy:

xcaddy build --with github.com/Rex--/caddy-git-server

Configuration

Since git_server is an http.handler module, you must manually define the order in which it is serviced relative to the other handlers caddy provides. The Caddyfile provides two ways to do this:

1. Route Block - You can manually define the routing order by putting the handlers into a route block. Even if you plan to use only the git_server handler, you still have to wrap it in a route block.

:8080 {
    route {
        <handler(s)>
    }
}

1. Global order directive - At the top of the Caddyfile you can define some global options that apply to the whole config. It is recommended that you order the git_server directive before file_server. Another option is ordering it last, this is useful for setups that only have the git_server.

{
    order git_server before file_server
        OR
    order git_server last
}

NOTE: Examples assume you have ordered the directive globally.

The simplest of configurations takes no arguments if you have defined a root:

git.example.com {
	root * /srv/git/
    git_server
}

Usage

The git_server will serve bare git repositories that are recursively contained within the root directory. The git_server only responds to git clients ('Git-Protocol' header is present OR a user agent starting with 'git'), unless the browse page is enabled, in which case a request to the root of each repository returns a small info page.

You can create a bare repository with the --bare flag, no special setup is required. It is only required that this bare repository be contained in the <root> directory (or subdirectory).

The following will clone a repository on example.com that is located at <root>/git/example.git:

git clone https://example.com/git/example.git

Reference

Caddyfile - The git_server directive attempts to mimic the built-in file_server directive +/- a few options.

git_server [match] [browse] {
    root <path>
    template_dir <path/to/templates/>
}

• <match> - request pattern to match
• browse - enable repository browser (available at the root of the repo)
• root <path> - root path of git directories
• template_dir <path> - directory containing templates that override the defaults.

JSON

{
    "handler": "git_server",
    "root": "<path>",
    "browse": true|false,
    "template_dir": "<path>"
}

Documentation

Index

• type GitBrowser
• type GitCommit
• type GitFile
• type GitRef
• type GitServer
  • func (GitServer) CaddyModule() caddy.ModuleInfo
  • func (gsrv *GitServer) Provision(ctx caddy.Context) error
  • func (gsrv *GitServer) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (gsrv *GitServer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (gsrv GitServer) Validate() error
• type StaticAssets

Types

type GitBrowser

type GitBrowser struct {
	Name        string
	Tagline     string
	Description string
	Path        string
	Host        string
	CloneURL    string
	Now         string
	Scheme      string
	Page        string
	Root        string

	Branches []GitRef
	Tags     []GitRef

	Commits []GitCommit

	Files []GitFile

	// Static assets
	Assets StaticAssets
}

type GitCommit

type GitCommit struct {
	// SHA1 commit hash
	Hash string
	//Author of commit
	Author string
	// Committer of commit
	Committer string
	// Commit message
	Message string
	// Creation date (done by Author)
	Date string
}

type GitFile

type GitFile struct {
	Name   string
	Mode   string
	Commit GitCommit
}

type GitRef

type GitRef struct {
	// SHA1 hash
	Hash string
	// Ref type string, either 'refs/heads' or 'refs/tags
	Type string
	// Name of branch or tag
	Name string
}

type GitServer

type GitServer struct {
	// Git http protocol to use: 'dumb' or 'smart' or 'both' (default)
	// Note this doesn't actually do anything currently, only the dumb protocol is implemented.
	Protocol string `json:"protocol,omitempty"`

	// Path to directory containing bare git repos (<repo>.git)
	Root string `json:"root,omitempty"`

	// Enable repo browser
	Browse      bool   `json:"browse,omitempty"`
	TemplateDir string `json:"template_dir,omitempty"`

	// If IgnorePrefix is defined we strip it from the URL path
	IgnorePrefix string `json:"ignore_prefix,omitempty"`

	// File server module that serves static git files
	// FileServerRaw json.RawMessage        `json:"file_server,omitempty" caddy:"namespace=http.handlers inline_key=handler"`
	FileServer *fileserver.FileServer `json:"-"`
	// contains filtered or unexported fields
}

func (GitServer) CaddyModule

func (GitServer) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*GitServer) Provision

func (gsrv *GitServer) Provision(ctx caddy.Context) error

func (*GitServer) ServeHTTP

func (gsrv *GitServer) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements http.MiddlewareHandler

func (*GitServer) UnmarshalCaddyfile

func (gsrv *GitServer) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Unmarshal caddyfile directive into a GitServer

func (GitServer) Validate

func (gsrv GitServer) Validate() error

type StaticAssets

type StaticAssets struct {
	GitIcon string
}