a97c673158
just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do!
125 lines
4.9 KiB
Markdown
125 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).
|
|
|
|
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.
|