repo2html/documentation/create-a-git-forge-with-repo2html.md

Create a Git forge with repo2html

This tutorial teaches you how to use repo2html as a post-receive hook to auto-generate HTML webpages for bare Git repositories on a remote web server after you git push to them.

A Git forge is a website that provides HTML representations of Git repositories, so visitors don't need to clone repositories to view their contents.

Page contents

• Requirements
• Prepare your server
  • Set up a git user
  • Set up nginx
  • Install repo2html
  • Set up a post-receive hook
  • Enable cloning over git://
• Test your post-receive hook locally

Requirements

• Chicken Scheme, and eggs:
  • clojurian
  • ersatz
  • lowdown
  • scss
  • srfi-1
  • srfi-13
  • srfi-14
  • sxml-transforms
  • symbol-utils
  • utf8
• Git
• nginx

Prepare your server

This section uses example.com as a placeholder value. Ensure you replace example.com with your own domain when following the procedures 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 to your server.
• 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.

Set 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.

After you've set up a git user, follow all procedures that don't require root as the git user.

Set 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.

Install repo2html

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

1. As root, run make dependencies.
2. Run make.
3. As root, run make install.

Set up a post-receive hook

1. Ensure you're in the repo2html Git repository.
2. Run mkdir ~/bin.
3. Run echo "PATH="~/bin:$PATH" >> ~/.profile.
4. Run cp assets/post-receive ~/bin.
5. Run chmod u+x ~/bin/post-receive.
6. Run ln -sf ~/bin/post-receive ~/projects/my-repository/hooks/post-receive.
7. Run cp assets/templates/default.html ~/bin.
8. In the assets/post-receive file, change path/to/directory/containing/template to ~/bin/default.html

Enable cloning over git://

1. Ensure you're in the repo2html Git repository.
2. As root, run cp assets/git-daemon.service /etc/systemd/system.
3. As root, run systemctl enable --now git-daemon.service.

Test your post-receive hook locally

This section uses example.com as a placeholder value. Ensure you replace example.com with your own domain when following the procedures 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.
8. Navigate to https://git.example.com/my-repository.