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
This commit is contained in:
m455
parent
031f975b2c
commit
907516d1d6
6 changed files with 233 additions and 177 deletions
148
README.md
148
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 <destination>`
|
||||
<!-- vim-markdown-toc GFM -->
|
||||
|
||||
run from a git repository, this command populates the directory `<destination>` 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.
|
||||
<!-- vim-markdown-toc -->
|
||||
|
||||
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 <destination> <template-directory>
|
||||
|
||||
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.
|
||||
- `<destination>` is the path to the directory that you want the HTML files to be generated in.
|
||||
- `<template-directory>` 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
@ -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 `<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.
|
||||
130
documentation/create-a-git-forge-with-repo2html.md
Normal file
130
documentation/create-a-git-forge-with-repo2html.md
Normal file
|
|
@ -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`.
|
||||
|
||||
|
||||
Loading…
Reference in a new issue