gitpages

A collection of scripts to securely webhost and publish git repositories.
git clone https://scm.kuandu.systems/git-raw/gitpages.git
Log | Files | Refs | README | LICENSE

README.md (3046B)

      1 # Gitpages
      2 
      3 Gitpages is a small static site generator for bare Git repositories on OpenBSD.
      4 It mirrors bare repositories into a web directory and generates HTML with
      5 [stagit](https://codemadness.org/stagit).
      6 
      7 Updates run through a queue and a dedicated service user, keeping Git hooks fast
      8 and the setup more secure.
      9 
     10 ## Layout
     11 
     12 ```txt
     13 push by git user
     14   -> post-receive hook
     15   -> queue file
     16 
     17 gitpages-update.sh by _gitpages via cron
     18   -> mirror GIT_SRC to GIT_RAW under WEB_ROOT
     19   -> generate HTML in GIT_HTML under WEB_ROOT
     20 
     21 httpd serves WEB_ROOT as www
     22 ```
     23 
     24 Example:
     25 
     26 ```txt
     27 /var/www/htdocs/scm.example.site/
     28 ├── git/
     29 │   └── myrepo/
     30 └── git-raw/
     31     └── myrepo.git
     32 ```
     33 
     34 ## Components
     35 
     36 - `install.sh` sets up users, directories, cron, and config.
     37 - `uninstall.sh` removes the service setup.
     38 - `gitpages-init-repos.sh` installs metadata and hooks for repositories.
     39 - `post-receive.hook` queues repository updates.
     40 - `gitpages-mirror-git.sh` mirrors bare repositories.
     41 - `gitpages.sh` generates stagit HTML.
     42 - `gitpages-update.sh` processes the queue.
     43 - `gitpages-regenerate.sh` rebuilds everything.
     44 
     45 ## Quick start
     46 
     47 ```sh
     48 doas pkg_add git stagit
     49 doas ./install.sh git /home/git/public-repos /var/www/htdocs/scm.example.site
     50 doas -u git ./gitpages-init-repos.sh
     51 doas -u _gitpages ./gitpages-regenerate.sh
     52 ```
     53 
     54 ## Configuration
     55 
     56 `/etc/gitpages.conf`:
     57 
     58 - `GIT_SRC`: source directory containing bare repositories.
     59 - `WEB_ROOT`: required document root for httpd.
     60 - `GIT_RAW`: subdirectory for mirrored repos.
     61 - `GIT_HTML`: subdirectory for generated HTML.
     62 - `ASSETS_DIR`: optional static files for repo pages.
     63 - `INDEX_TITLE`: optional title for `index.html`.
     64 - `INDEX_DESCRIPTION`: optional description for `index.html`.
     65 - `REPO_TITLE_DESCRIPTION`: optional repo title suffix.
     66 
     67 Defaults written by `install.sh`:
     68 
     69 - `GIT_RAW=git-raw`
     70 - `GIT_HTML=git`
     71 - `ASSETS_DIR=/var/gitpages/assets`
     72 
     73 ## httpd
     74 
     75 ```httpd
     76 server "scm.example.site" {
     77     listen on * port 80
     78     root "/htdocs/scm.example.site"
     79     location "/git/*" { directory auto index }
     80     location "/git-raw/*" { directory auto index }
     81 }
     82 ```
     83 
     84 ## Notes
     85 
     86 - Edit `/etc/gitpages.conf` to set page metadata or change paths.
     87 - When a new bare repository is added to `GIT_SRC`, run `gitpages-init-repos.sh` for it.
     88 - By default, `gitpages-update.sh` runs from `_gitpages` cron every 5 minutes.
     89 - Logs are written to `/var/log/gitpages/update.log`.
     90 - Pending jobs are in `/var/spool/gitpages/queue`.
     91 
     92 ## Security
     93 
     94 - The post-receive hook only writes entries to `/var/spool/gitpages/queue/`.
     95 - The queue directory is restricted to the `gitpages` group.
     96 - Failed jobs stay queued for retry.
     97 - `_gitpages` is a service user with no login shell.
     98 - `_gitpages` performs mirroring and HTML generation.
     99 - `httpd` serves only the generated files under `WEB_ROOT`.
    100 - `WEB_ROOT` is owned by `root:wheel`; only the generated subdirectories are writable by `_gitpages`.
    101 - The `git` user must have read access to `GIT_SRC`.
    102 - Source repositories and public web output are kept separate.