repo2html/build-a-git-forge.md

how to use repo2html to build a git forge

This document describes how one might use repo2html (this project) together with a webserver and some configuration to build a static git forge.

A git forge is a website that presents one or more git repositories for visitors to browse, and also allows them to git clone, pull, and optionally push commits to and from those repositories, while automatically updating the browsable representation.

Some extant git forge services include: GitHub, BitBucket, GitLab, SourceForge, Sourcehut, and Codeberg.

Software that can be used to build a self-hosted git forge includes: self-hosted gitlab, gogs, gitea, cgit, and gitweb.

Since repo2html is configured herein to output updated HTML files only in response to a git push, the git forge described here requires no complex server software like the ones above. Its webserver is configured to serve static html files from disk.

quickstart

1. ensure you've set up a web directory and have replaced the REPO2HTML_PREFIX value in the post-receive and git-daemon.service files
2. you've created a git user, and are logged in as the git user
3. as root, run make dependencies
4. run make
5. as root, run make install
6. run mkdir ~/projects && git init --bare my-repository
7. run cp post-receive ~/projects/my-repository/hooks/
8. run chmod u+x ~/projects/my-repository/hooks/post-receive
9. run cp git-daemon.service /etc/systemd/system/

server setup

this section uses example.com as a placeholder value. ensure you replace example.com with your own domain below.

this section assumes the following about your server:

• you've generated public and private ssh keys on your local machine
• you can access your server through ssh and have root access
• you manage your firewall with ufw
• you use nginx as your web server
• you use letsencrypt to manage TLS certificates
• you've added an A record for git.example.com

setting up a git user

ensure you're in the repo2html git repository, and follow the steps below:

1. as root, run adduser git
2. as root, run mkdir /var/www/git && chown git:git /var/www/git
3. as root, run ufw allow 9418
4. run su git
5. run mkdir ~/.ssh && chmod 700 ~/.ssh
6. run touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
7. add your public ssh key from your local machine to ~/.ssh/authorized_keys
8. run mkdir ~/projects
9. run git init --bare my-repository

setting up nginx

1. as root, add the following contents to /etc/nginx/sites-available/git.example.com:

    server {
        root /var/www/git;
        index index.html;
        server_name git.example.com;
    }
   

2. as root, run ln -s /etc/nginx/sites-available/git.example.com /etc/nginx/sites-enabled/

3. as root, run nginx -t to test your nginx configuration

4. as root, run certbot, and follow the prompts

5. as root, run systemctl restart nginx

installation

ensure you're in the repo2html git repository, and follow the steps below:

1. run make install as root
2. run cp post-receive ~/projects/my-repository/hooks/
3. run chmod u+x ~/projects/my-repository/hooks/post-receive
4. run cp git-daemon.service /etc/systemd/system/ as root
5. run systemctl enable --now git-daemon.service as root

using repo2html as a post-receive hook

this section uses example.com as a placeholder value. ensure you replace example.com with your own domain below.

on your local machine, follow the steps below:

1. run git init my-repository
2. run cd my-repository
3. run echo "hello" > my-file.txt
4. run git add my-file.txt
5. run git commit -m "my first commit"
6. run git remote add origin git@example.com:~/projects/my-repository
7. run git push

configuration

this section uses example.com as a placeholder value. ensure you replace example.com with your own domain below.

you can configure repo2html by changing environment variables in the post-receive hook file.

for details about the environment variables, refer to the list below:

• REPO2HTML_PREFIX: the web directory where repo2html generates static git repositories. for example, /var/www/git/.
• REPO2HTML_CLONE_URL: the url that people will use when downloading your git repository. if you have git-daemon set up, then you can prefix the url with git://. otherwise, prefix the url with http://. for example, git://git.example.com. note: avoid slashes at the end of the url.
• REPO2HTML_TITLE: the text that populates the <title> html tag.
• REPO2HTML_DESCRIPTION: a string that populates the description meta information about your git repository.
• REPO2HTML_H1: the text that populates the <h1> html tag.