From 907516d1d687de8815d5856b081be5fa6f709e45 Mon Sep 17 00:00:00 2001 From: m455 Date: Tue, 20 Dec 2022 00:42:35 -0500 Subject: [PATCH] Updated documentation and cleaned up directory tree - Updated documentation, so it's very nice for pho4cexa <3 - Moved helper/example files to an assets directory (feel free to rearrange all of these again if you have any better ideas :D - Renamed and moved tutorial file to make it more descriptive - Removed old environment variables from post-receive hook example file --- README.md | 148 ++++++++++++------ .../git-daemon.service | 0 post-receive => assets/post-receive | 6 +- {templates => assets/templates}/default.html | 0 build-a-git-forge.md | 126 --------------- .../create-a-git-forge-with-repo2html.md | 130 +++++++++++++++ 6 files changed, 233 insertions(+), 177 deletions(-) rename git-daemon.service => assets/git-daemon.service (100%) rename post-receive => assets/post-receive (91%) rename {templates => assets/templates}/default.html (100%) delete mode 100644 build-a-git-forge.md create mode 100644 documentation/create-a-git-forge-with-repo2html.md diff --git a/README.md b/README.md index d1bc96a..4b7ab60 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,39 @@ # repo2html -generates static html pages for browsing the contents of a git repository. +A command-line tool that generates a static HTML representation of a Git repository. -## basic usage +## Page contents -`repo2html ` + -run from a git repository, this command populates the directory `` with html files that provide a web-browsable view of the contents of repository. +- [Features](#features) +- [Requirements](#requirements) +- [Usage](#usage) +- [Installation](#installation) +- [Configuration](#configuration) + - [Templates](#templates) + - [Environment variables](#environment-variables) +- [Setting up a Git forge on your web server](#setting-up-a-git-forge-on-your-web-server) +- [Alternative Git-to-HTML tools](#alternative-git-to-html-tools) +- [Existing Git forges](#existing-git-forges) +- [Existing Git forge software](#existing-git-forge-software) +- [Todos](#todos) -note: changes must be at least committed before they will appear in the html output. -more precisely: the html output represents the state of the `HEAD` commit, not that of the current work-tree. + -you may also cause this html directory to be automatically updated upon every `git push`, by invoking repo2html from a git hook. -we describe how to use this technique to [build a static git forge](build-a-git-forge.md.html). +## Features -## features +- Static html files +- Customizable templates +- Can be used as a standalone command-line tool, or in a Git hook +- Built-in, plaintext issue support +- Image support +- Markdown files are rendered as HTML +- No resident background process -- static html files -- image support -- markdown files are rendered as html -- no resident background process +## Requirements -## disclaimer - -no one is liable if this software breaks, deletes, corrupts, or ruins anything - -## requirements - -- [chicken scheme](https://call-cc.org/), and eggs: +- [Chicken Scheme](https://call-cc.org/), and eggs: - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian) - [ersatz](https://wiki.call-cc.org/eggref/5/ersatz) - [lowdown](https://wiki.call-cc.org/eggref/5/lowdown) @@ -38,46 +44,94 @@ no one is liable if this software breaks, deletes, corrupts, or ruins anything - [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms) - [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils) - [utf8](https://wiki.call-cc.org/eggref/5/utf8) -- git +- Git -### installation +## Usage -this compiles the binary `repo2html` and place it in `/usr/local/bin`. + repo2html -1. ensure you're in the repo2html git repository -2. as root, run `make dependencies` -3. run `make` -4. run `make install` as root +Run `repo2html` inside the root directory of a Git repository or a bare Git repository. -if you wish, you may then uninstall the chicken scheme compiler. +- `` is the path to the directory that you want the HTML files to be generated in. +- `` is the path to the directory that contains a + `default.html` file. Refer to `assets/templates/default.html` for an example + `default.html` file. -if you prefer, the file `main.scm` may be used as the repo2html executable instead of compiling a binary file, but it will be slower, and requires that the chicken scheme interpreter remain installed on your system. +The HTML that's generated represents the state of the `HEAD` commit, not the +current state of the work tree. -## how it works +## Installation -TODO +This section guides you through installing the required dependencies, compiling +a binary, and then installing the binary. By default, `repo2html` installs +into the `/usr/local/bin` directory. -## todos +1. Ensure you're in the `repo2html` git repository. +2. As root, run `make dependencies` to install the required Chicken Scheme eggs. +3. Run `make` to compile a static `repo2html` binary in the current directory. +4. As root, run `make install` to copy the `repo2html` binary into the `/usr/local/bin` directory. -- **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 -- **documentation/feature**: use post-update rather than post-receive hook for simplicity -- **documentation**: also describe use with post-commit hook -- **feature**: multi-page or collapse-able files list -- **feature**: branches and releases (tags) -- **feature**: clickable line numbers in source files -- **feature**: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.? -- **feature**: syntax highlighting? -- **feature**: markdown-render git log text -- **feature**: other mechanisms for header id application like uniqueness checking, sequential numbering +**Note**: If you want to use `main.scm` as the `repo2html` executable, instead +of compiling a static binary file, then run +`cp main.scm /usr/local/bin/repo2html` as root. -## license: agpl-3.0+ +## Configuration -Copyright 2022 [Jesse Laprade](https://m455.casa). -This software is released under the terms of the [GNU Affero General Public License](https://www.gnu.org/licenses/agpl.html), version 3 or any later version. +You can `repo2html` by changing the following items: -## alternatives +- [Templates](#templates) +- [Environment variables](#environment-variables) + +### Templates + +You can customize `repo2html` by editing the `assets/templates/default.html`, and then specifying the path to the `default.html` file as the second command-line argument when running `repo2html`. + +For example, if you placed a `default.html` file in `~/bin/templates`, and you serve HTML files from `/var/www/git`, then you run `repo2html /var/www/git ~/bin/templates`. + +### Environment variables + +You can provide a generic description by setting the `REPO2HTML_DESCRIPTION` environment variable, or by adding a description in a `description` file in the root directory of your Git repository. + +## Setting up a Git forge on your web server + +Refer to [Create a Git forge with repo2html](documentation/create-a-git-forge-with-repo2html.md.html) to learn how use +`repo2html` as a post-receive hook to auto-generate HTML webpages for bare Git repositories on a remote web server. + +## Alternative Git-to-HTML tools - [stagit](https://codemadness.org/git/stagit/file/README.html) - [depp](https://git.8pit.net/depp.git/) - [git-arr](https://blitiri.com.ar/p/git-arr/) + +## Existing Git forges + +- [NotABug](https://notabug.org/) +- [Codeberg](https://codeberg.org/) +- [sourcehut](https://sourcehut.org/) +- [GitLab](https://gitlab.com/) +- [Bitbucket](https://bitbucket.org/product/) +- [SourceForge](https://sourceforge.net/) +- [GitHub](https://github.com/) + +## Existing Git forge software + +[GitLab](https://about.gitlab.com/install/) +[Gogs](https://gogs.io/) +[Gitea](https://gitea.io/) +[cgit](https://git.zx2c4.com/cgit/) +[GitWeb](https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb) +[legit](https://git.icyphox.sh/legit) + +## Todos + +- **documentation/feature**: use post-update rather than post-receive hook for simplicity +- **documentation**: also describe use with post-commit hook +- **documentation**: describe readme, license, and issues behaviours +- **feature**: multi-page or collapse-able files list +- **feature**: branches and releases (tags) +- **feature**: clickable line numbers in source files +- **feature**: display binary files as output from binary-file analysis tools like `hexdump`, `xxd`, `dumpelf`, `elfls`, `readelf`, etc.? +- **feature**: syntax highlighting? +- **feature**: markdown-render git log text +- **feature**: other mechanisms for header id application like uniqueness checking, sequential numbering + diff --git a/git-daemon.service b/assets/git-daemon.service similarity index 100% rename from git-daemon.service rename to assets/git-daemon.service diff --git a/post-receive b/assets/post-receive similarity index 91% rename from post-receive rename to assets/post-receive index e400f5e..8e08257 100755 --- a/post-receive +++ b/assets/post-receive @@ -6,10 +6,7 @@ # The toplevel path containing directories of static pages [ "$REPO2HTML_PREFIX" ] || export REPO2HTML_PREFIX=/var/www/git # The toplevel clone url for repos. -export REPO2HTML_CLONE_URL=git://git.example.com -export REPO2HTML_TITLE=git.example.com export REPO2HTML_DESCRIPTION="sherry's git repositories" -export REPO2HTML_H1=git.example.com # hueristic attempt to detect a reasonable default for the name of this repo # you may want to adjust this if you have e.g. sub-directories containing repos @@ -52,4 +49,5 @@ else exit 1 fi -repo2html "$REPO2HTML_PREFIX/$repo_name" +# the second argument here should be a directory containing "default.html" +repo2html "$REPO2HTML_PREFIX/$repo_name" "path/to/directory/containing/template" diff --git a/templates/default.html b/assets/templates/default.html similarity index 100% rename from templates/default.html rename to assets/templates/default.html diff --git a/build-a-git-forge.md b/build-a-git-forge.md deleted file mode 100644 index ddc5b0a..0000000 --- a/build-a-git-forge.md +++ /dev/null @@ -1,126 +0,0 @@ -# how to use repo2html to build a git forge - -this document describes how one might use [repo2html](index.html) (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](https://gitlab.com/), -sourceforge, -[sourcehut](https://sourcehut.org/), and -[codeberg](https://codeberg.org/). - -software that can be used to build a self-hosted git forge includes: -self-hosted [gitlab](https://about.gitlab.com/install/), -[gogs](https://gogs.io/), -[gitea](https://gitea.io/), -[cgit](https://git.zx2c4.com/cgit/), and -[gitweb](https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb). - -the git forge described here requires no continuously-running software beyond a simple webserver. -we configure repo2html to output updated html files only in response to a `git push`, -which the webserver then serves 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 `` 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. diff --git a/documentation/create-a-git-forge-with-repo2html.md b/documentation/create-a-git-forge-with-repo2html.md new file mode 100644 index 0000000..20ee280 --- /dev/null +++ b/documentation/create-a-git-forge-with-repo2html.md @@ -0,0 +1,130 @@ +# 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 + +<!-- vim-markdown-toc GFM --> + +- [Requirements](#requirements) +- [Prepare your server](#prepare-your-server) + - [Set up a git user](#set-up-a-git-user) + - [Set up nginx](#set-up-nginx) + - [Install repo2html](#install-repo2html) + - [Set up a post-receive hook](#set-up-a-post-receive-hook) + - [Enable cloning over git://](#enable-cloning-over-git) +- [Test your post-receive hook locally](#test-your-post-receive-hook-locally) + +<!-- vim-markdown-toc --> + +## Requirements + +- [Chicken Scheme](https://call-cc.org/), and eggs: + - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian) + - [ersatz](https://wiki.call-cc.org/eggref/5/ersatz) + - [lowdown](https://wiki.call-cc.org/eggref/5/lowdown) + - [scss](https://wiki.call-cc.org/eggref/5/scss) + - [srfi-1](https://wiki.call-cc.org/eggref/5/srfi-1) + - [srfi-13](https://wiki.call-cc.org/eggref/5/srfi-13) + - [srfi-14](https://wiki.call-cc.org/eggref/5/srfi-14) + - [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms) + - [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils) + - [utf8](https://wiki.call-cc.org/eggref/5/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`. + +