diff --git a/README.md b/README.md index 632942a..bad1704 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ Assuming the current directory is a Git repository, this command populates *DEST 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 (if any). -You may also cause this directory to be automatically updated upon every `git push`, by invoking *repo2html* as a Git *post-receive hook*. +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 @@ -20,14 +21,6 @@ You may also cause this directory to be automatically updated upon every `git pu - markdown files are rendered as html - no resident background process -## caveats - -- need better detection and rendering of binary files -- directory tree is shown as a flat list of files -- no commit log yet -- no line numbers yet -- no customizable templates yet - ## disclaimer no one is liable if this software breaks, deletes, corrupts, or ruins anything @@ -41,116 +34,18 @@ no one is liable if this software breaks, deletes, corrupts, or ruins anything - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian) - git -## quickstart +### installation -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` - -### 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: +this compiles the binary `repo2html` and place it in `/usr/local/bin`. 1. ensure you're in the repo2html git repository 2. as root, run `make dependencies` 3. run `make` +4. run `make install` as root -### installation +if you wish, you may then uninstall the chicken scheme compiler. -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. +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. ## how it works @@ -160,16 +55,16 @@ TODO - **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 - -## hopes - +- **documentation/feature**: use post-update rather than post-receive hook for simplicity +- **documentation**: also describe use with post-commit hook +- **feature**: need better detection and rendering of binary files +- **feature**: multi-page or collapse-able files list +- **feature**: commit log +- **feature**: branches and releases (tags) - **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 links: Releases, Branches, Commits (Log) - -## should we...? - +- **feature**: customizable templates - **feature**: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.? +- **feature**: syntax highlighting? ## license: agpl-3.0+ diff --git a/build-a-git-forge.md b/build-a-git-forge.md new file mode 100644 index 0000000..d01ff27 --- /dev/null +++ b/build-a-git-forge.md @@ -0,0 +1,125 @@ +# 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). + +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.