README.md (5413B)
1 # gitpages 2 3 `gitpages` generates static Git repository web pages using [stagit](https://git.codemadness.org/stagit/). 4 5 It maintains a web-facing mirror of bare Git repositories and generates static HTML pages from them. Repository updates are triggered by Git `post-receive` hooks and processed asynchronously through a queue. 6 7 `gitpages` itself is a POSIX shell application. The included `install.sh` is specific to OpenBSD. 8 9 ## Requirements 10 11 - POSIX-compatible `/bin/sh` 12 - Git 13 - [stagit](https://git.codemadness.org/stagit/) 14 - `stagit-index` 15 16 The installer also expects the OpenBSD utilities and account-management commands provided by the base system. 17 18 ## Installation 19 20 Run the installer as root: 21 22 ./install.sh <git-user> <git-src> <web-root> 23 24 For example: 25 26 ./install.sh git /srv/git /var/www/htdocs 27 28 Where: 29 30 - `git-user` is the existing Unix account used to receive Git pushes. 31 - `git-src` is the directory containing the bare Git repositories. 32 - `web-root` is the directory from which the generated pages will be served. 33 34 The installer creates the following system resources: 35 36 /usr/local/sbin/gitpages 37 /usr/local/sbin/gitpages.post-receive.hook 38 /etc/gitpages.conf 39 /var/gitpages/ 40 /var/log/gitpages/ 41 /var/spool/gitpages/queue/ 42 43 It also creates the `_gitpages` service account and `gitpages` group, configures `newsyslog`, and installs a cron job that processes the update queue every five minutes. 44 45 If `/etc/gitpages.conf` already exists, the installer leaves it unchanged. 46 47 ## Repository setup 48 49 After installation, prepare the repositories: 50 51 gitpages setup /srv/git 52 53 `setup` is interactive. For each bare repository it asks for: 54 55 - description 56 - owner/contact 57 - URL 58 59 It also installs the `post-receive` hook required to queue repository updates. 60 61 If no source directory is specified, `gitpages setup` uses `GIT_SRC` from `/etc/gitpages.conf`: 62 63 gitpages setup 64 65 The account running `gitpages setup` must have write access to the source repositories because the command modifies their metadata and hooks. 66 67 ## How it works 68 69 A push to a configured bare repository runs the `post-receive` hook. The hook places the repository in the update queue. 70 71 The `_gitpages` cron job periodically runs: 72 73 gitpages process_queue 74 75 For each queued repository, `gitpages`: 76 77 1. mirrors the repository into the web-facing `git-raw` directory; 78 2. runs `stagit` to generate the repository pages; 79 3. copies optional assets; 80 4. publishes the generated pages; 81 5. regenerates the repository index. 82 83 The queue and generated files are kept outside the Git source tree. 84 85 ## Directory layout 86 87 With the default installation: 88 89 /var/gitpages/ 90 ├── assets/ 91 └── staging/ 92 93 /var/spool/gitpages/ 94 └── queue/ 95 96 /var/log/gitpages/ 97 98 The web root contains: 99 100 <web-root>/ 101 ├── git-raw/ 102 │ └── *.git 103 └── git/ 104 ├── index.html 105 └── <repository>/ 106 └── ... 107 108 `git-raw` contains bare repository mirrors suitable for serving Git's smart/dumb HTTP data. `git` contains the generated stagit HTML. 109 110 ## Configuration 111 112 The default configuration file is: 113 114 /etc/gitpages.conf 115 116 A minimal configuration is: 117 118 GIT_SRC=/srv/git 119 WEB_ROOT=/var/www/htdocs 120 GIT_RAW=git-raw 121 GIT_HTML=git 122 ASSETS_DIR=/var/gitpages/assets 123 124 Optional settings can be added to customize generated pages: 125 126 INDEX_TITLE=My Git Repositories 127 INDEX_DESCRIPTION=Source code and project repositories 128 REPO_TITLE_DESCRIPTION= - My Git repositories 129 130 `gitpages generate` accepts an alternative configuration file: 131 132 gitpages generate -c /path/to/gitpages.conf 133 134 ## Commands 135 136 ### `gitpages setup [SRC]` 137 138 Prepare all bare repositories in `SRC` for use with `gitpages`. 139 140 If `SRC` is omitted, `GIT_SRC` from `/etc/gitpages.conf` is used. 141 142 ### `gitpages generate [-c CONFIG] [REPO]` 143 144 Generate static pages. 145 146 Without `REPO`, all repositories configured in `GIT_SRC` are processed. 147 148 With `REPO`, only the specified repository is generated. 149 150 For a full generation, repositories are first mirrored from `GIT_SRC` into `GIT_RAW`. 151 152 ### `gitpages process_queue [-c CONFIG]` 153 154 Process repositories waiting in the update queue. 155 156 This command is normally run automatically by cron: 157 158 */5 * * * * /usr/local/sbin/gitpages process_queue 159 160 A lock prevents multiple queue processors from running simultaneously. 161 162 ## Web server 163 164 The generated files can be served by any web server capable of serving static files and Git HTTP repository data. 165 166 On OpenBSD, `httpd` can be used to serve the configured web root. 167 168 If `httpd` is configured with a `chroot`, the `WEB_ROOT` path used by `gitpages` refers to the filesystem path on the host, while the corresponding path in the `httpd` configuration is relative to its chroot. 169 170 ## Uninstallation 171 172 Run the uninstaller as root: 173 174 ./uninstall.sh 175 176 The uninstaller removes the files and system resources created by the installer, including: 177 178 - installed `gitpages` scripts 179 - `_gitpages` service account 180 - `gitpages` group 181 - `/var/gitpages` 182 - `/var/log/gitpages` 183 - `/var/spool/gitpages/queue` 184 - the `newsyslog` entry 185 186 It does **not** remove: 187 188 - Git repositories 189 - the web root 190 - generated web content 191 - `/etc/gitpages.conf` 192 193 The default assets directory under `/var/gitpages/assets` may contain administrator-supplied files. The uninstaller asks for confirmation before removing `/var/gitpages`.