a916af24aa
m455, i lost the advice you gave me previously, detailing conventions you'd like to conform to when writing documentation for this project. i tried to make some changes here that conform to what pieces i remember but probably got some of it wrong. would you mind reiterating your recommendations in an email or text file for me? thanks!!
126 lines
4.9 KiB
Markdown
126 lines
4.9 KiB
Markdown
# 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.
|