gitpages

commit 7867beea464dece7abb951fb3f83cb1ab2709470
parent 214f3ce1dd0039621cf94cd4ac62ac949d19cfa6
Author: Fred Großkopf <fred@kuandu.systems>
Date:   Wed,  6 May 2026 14:14:00 +0200

Updates README

Diffstat:
M
README.md
 | 
129
+++++++++++++++++++++++++++++++++++++++----------------------------------------

1 file changed, 64 insertions(+), 65 deletions(-)
diff --git a/README.md b/README.md
@@ -1,88 +1,87 @@
-# Git Web Hosting (OpenBSD + httpd + stagit)
+# Gitpages
 
-Static git web interface using bare repos, httpd, and stagit.
+Gitpages is a minimalist static site generator for Git repositories on OpenBSD.
+It mirrors bare repositories into a web-accessible directory and generates
+browsable HTML using [stagit](https://codemadness.org/stagit).
 
-## Directory Structure
+Updates run asynchronously via a queue and a dedicated service user, keeping Git
+hooks fast and safe.
 
-Example directory structure:
+## How it works
 
-```
-scm.mydomain.com/
-├── raw-git/     ← Mirrored bare repos (git-http-backend)
-└── git/         ← Stagit HTML (static web pages)
-```
-
-## Scripts
 
-### mirror-git.sh - Mirror bare git repos
+1. A developer pushes to a bare repository.
+2. The post-receive hook writes the repository path into a queue file.
+3. A cron job (running as `_gitpages`) processes queued jobs:
+   - Mirrors the repository into `GIT_RAW`
+   - Generates HTML into `GIT_HTML` using stagit
+4. httpd serves both:
+   - Raw repositories (for cloning)
+   - Generated HTML (for browsing)
 
-
-`mirror-git.sh` replicates bare Git repositories from a secure central server to a 
-web-accessible location, enabling HTTP(S) Git access and static HTML generation 
-(stagit/gitpages) while keeping push targets isolated from public web exposure.
-
-```
-./mirror-git.sh /home/vcs/git /var/www/htdocs/scm.mydomain.com/raw-git
+```txt
+Push → post-receive → queue → cron mirrors → stagit → httpd serves both raw repos + HTML
 ```
 
-### gitpages-init.sh - Initial setup
+## Example layout
 
-`gitpages-init.sh` mirrors Git repositories and generates HTML files in one go.
-
-```
-./init-gitweb.sh /home/vcs/git /var/www/htdocs/scm.mydomain.com/raw-git /var/www/htdocs/scm.mydomain.com/git
+```txt
+https://scm.example.com/
+├── git/          ← HTML browsing (stagit)
+│   └── myrepo/
+└── git-raw/      ← HTTP clone
+    └── myrepo.git
 ```
 
-### gitpages.sh - Generate HTML only
+## Components
 
-A single repo:
+**Component** | **Description**
+-- | -- 
+`install.sh` | Sets up users, cron, directories, config  
+`uninstall.sh` | Removes service user, cron, directories, log rotation  
+`gitpages-init-repos.sh` | Prompts repo metadata, installs hooks  
+`post-receive.hook` | Writes repo path to queue on push  
+`gitpages-mirror-git.sh` | Copies repos + `update-server-info`  
+`gitpages.sh` | stagit HTML generation  
+`gitpages-update.sh` | Queue processor (cron)  
+`gitpages-regenerate.sh` | Full rebuild  
 
-```
-./gitpages.sh /raw-git/myrepo.git /git/
-```
 
-All repos:
+## Quick start
 
-```
-./gitpages.sh /raw-git/ /git/
+```sh
+doas pkg_add git stagit
+doas ./install.sh git          # "git": user that owns the git repos
+doas vi /etc/gitpages.conf
+doas -u git ./gitpages-init-repos.sh /home/git/repos  
+doas -u _gitpages -s /bin/sh ./gitpages-regenerate.sh
 ```
 
-With assets:
-
-```
-./gitpages.sh /raw-git/ /git/ /assets/
-```
-
-When `ASSETS_DIR` is given:
-
-- Assets are copied into the gitpages root
-- Then symlinked into every repo‑HTML directory (e.g., `git/myrepo/favicon.ico` → `../favicon.ico`)
-
-### Customizing HTML
-
-You can use an optional config file `gitpages.conf` to change titles and
-descriptions in stagit and stagit-index output.
-
-Example:
+## Configuration (/etc/gitpages.conf)
 
 ```ini
-SITE_NAME=mycompany
-INDEX_TITLE=New Title
-INDEX_DESCRIPTION=New Description
-REPO_TITLE_DESCRIPTION= | $SITE_NAME
+GIT_SRC=/var/git/repos                       # Source bare repos (*.git)
+WEB_ROOT=/var/www/htdocs/scm.example.com     # httpd document root
+GIT_RAW=git-raw                              # Raw repos subdirectory
+GIT_HTML=git                                 # HTML output subdirectory
+ASSETS_DIR=/var/gitpages/assets              # Static files (CSS/JS) copied to repo pages
+INDEX_TITLE=My Git repositories              # Index.html <title>
+INDEX_DESCRIPTION=...                        # Index.html description
+REPO_TITLE_DESCRIPTION= - My Project         # Replaces "- DESCRIPTION" in "File - REPO - DESCRIPTION"
 ```
-
-If gitpages.conf exists or is passed with -c, gitpages.sh rewrites:
-
-- index.html title and description:
-
-```html
-<title>New Title</title>
-<span class="desc">New Description</span>
+## httpd
+
+```httpd
+server "scm.example.com" {
+    listen on * port 80
+    root "/htdocs/scm.example.com"
+    location "/git/*" { directory auto index }
+}
 ```
 
-- repository pages title tags:
+## Notes
 
-```html
-<title>Log - myrepo | mycompany</title>
-```
+- Failed jobs stay queued for retry
+- Logs: `/var/log/gitpages/update.log`  
+- `ls /var/spool/gitpages/queue | wc -l` = pending jobs
+- One runner at a time (lockfile)