github/repo2html
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

simplify main readme by moving "git forge" specifics elsewhere

Browse source 
just a suggestion; don't feel obligated to merge. you know technical
writing and documentation better than i do!
This commit is contained in:
pho4cexa 2022-12-09 08:52:38 -08:00 committed by m455
parent 335a444dc4
commit a97c673158
2 changed files with 140 additions and 120 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

135
README.md
View file

@ -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 `<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.
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+

125
build-a-git-forge.md Normal file
View file

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