repo2html/README.md

# repo2html

a command-line tool that turns git repositories in html pages

## features

- static html files
- image support (we're working on this)
- svg support (we're working on this)
- markdown files are rendered as html (we're working on this)
- no background process (unless you're using this tool as a post-receive hook, then you only need git-daemon running)
- default repository view is an html-rendered README.md file

## caveats

- binary file contents are just... shown
- directory tree is shown as a flat list of files, so git repositories with
  many files and directories will look awful
- no commit log (yet?)
- no line numbers (yet?)

## disclaimer

no one is liable if this software breaks, deletes, corrupts, or ruins anything

## requirements

- [chicken scheme](https://call-cc.org/)
- [utf8 egg](https://wiki.call-cc.org/eggref/5/utf8)
- [lowdown egg](https://wiki.call-cc.org/eggref/5/lowdown)
- [sxml-transforms egg](https://wiki.call-cc.org/eggref/5/sxml-transforms)
- [clojurian egg](https://wiki.call-cc.org/eggref/5/clojurian)
- git

**note**: if you have chicken scheme installed, then you can install the eggs
above by running `make dependencies` as root.

## compilation

chicken scheme runs faster if it's compiled to a binary file. by default, the
binary is named `repo2html`, and is installed in `/usr/local/bin`.

to compile repo2html into a binary file, follow the steps below:

1. ensure you're in the repo2html git repository
2. as root, run `make dependencies`
3. run `make`

## 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`
3. as root, run `chown git:git /var/www/git`
4. as root, run `ufw allow 9418`
5. run `su git`
6. run `mkdir ~/.ssh && chmod 700 ~/.ssh`
7. run `touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys`
8. add your public ssh key from your local machine to `~/.ssh/authorized_keys`
9. run `mkdir -p ~/projects/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.

## how it works

TODO

## todos

- **documentation**: convert a lot of the stuff i (m455) made in the readme into an e2e tutorial
- **documenation**: scope the readme audience to folks who kind of know what they're doing with servers
- **feature** : if no README.md file exists in the root directory of the repository, then don't create the "about" nav link. instead, make the files page the index.html
- **feature**: add a "license" nav link if a LICENSE file exists in the root directory of the repository. if no LICENSE file exists, then don't create the "license" nav link

## hopes

- **feature**: clickable line numbers in source files
- **feature**: make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?)
- **feature**: nav link: Releases