https://github.com/hubzero/hzforge
Install, diagnose, and repair HUBzero Forge services (Subversion, Git, gitExternal, Trac) as self-contained Apache drop-ins — independent of the m4 template and hzcms.
https://github.com/hubzero/hzforge
apache git hubzero mod-python mod-wsgi python subversion trac
Last synced: 5 days ago
JSON representation
Install, diagnose, and repair HUBzero Forge services (Subversion, Git, gitExternal, Trac) as self-contained Apache drop-ins — independent of the m4 template and hzcms.
- Host: GitHub
- URL: https://github.com/hubzero/hzforge
- Owner: hubzero
- License: mit
- Created: 2026-05-24T21:51:05.000Z (13 days ago)
- Default Branch: main
- Last Pushed: 2026-05-24T22:47:17.000Z (13 days ago)
- Last Synced: 2026-05-24T23:29:42.954Z (13 days ago)
- Topics: apache, git, hubzero, mod-python, mod-wsgi, python, subversion, trac
- Language: Python
- Homepage: https://hubzero.github.io/hzforge/
- Size: 60.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
hzforge
Install, diagnose & repair HUBzero Forge services — Apache drop-ins, no m4.
---
`hzforge` installs, uninstalls, diagnoses, and repairs **HUBzero Forge
services** — Subversion, Git, gitExternal, and Trac — as
self-contained Apache **drop-ins**, independent of the m4 vhost template.
On a HUBzero hub each tool gets a project area under `/tools//…`:
| Service | URL space | Apache mechanism |
|---------------|------------------------------------|------------------|
| `svn` | `/tools//svn` | `mod_dav_svn` (``) |
| `git` | `/tools//git/` | `git-http-backend` (`ScriptAliasMatch`) |
| `gitExternal` | `/tools//gitExternal/` | `git-http-backend` (`ScriptAliasMatch`) |
| `trac` | `/tools//{wiki,timeline,browser,ticket,…}` | mod_wsgi (default) or mod_python |
hzforge writes **one config file per service** at
`/etc/httpd/.conf.d/00-forge-.conf`, picked up by the vhost's existing
`IncludeOptional .conf.d/*.conf` — so it never edits the m4-generated
vhost or requires regenerating the vhost. The per-tool `svn.conf` / `git.conf` blocks
still come from the hub's existing MySQL-driven generator; hzforge only *includes*
them and shields them from the CMS catch-all rewrite.
## Documentation
Full docs: **** (sources under [`docs/`](docs/)).
HUBzero Trac plugins being ported alongside hzforge live under [`plugins/`](plugins/).
- [Summary](https://hubzero.github.io/hzforge/overview/summary/) — what it is, at a glance
- [Motivations](https://hubzero.github.io/hzforge/overview/motivations/) — why it bypasses the m4 vhost
- [Architecture](https://hubzero.github.io/hzforge/reference/architecture/) — how the drop-ins are wired
- [Services](https://hubzero.github.io/hzforge/reference/services/) — the four services in detail
- [Usage](https://hubzero.github.io/hzforge/operations/usage/) — full command reference
- [Manual installation](https://hubzero.github.io/hzforge/operations/manual-install/) — by-hand steps for each handler/service set
- [Migration](https://hubzero.github.io/hzforge/operations/migration/) — mod_python → mod_wsgi
## Quickstart
Run as **root**. Services are **positional** (space- or comma-separated); a bare
`hzforge` prints help. Preview anything with `--dry-run`.
```sh
sudo python3 hzforge.py install # all services
sudo python3 hzforge.py install trac # one service
sudo python3 hzforge.py install svn git trac
sudo python3 hzforge.py uninstall git # stop serving git (data kept)
sudo python3 hzforge.py doctor # diagnose (exit 1 on FAIL)
sudo python3 hzforge.py doctor git # diagnose one service
sudo python3 hzforge.py repair # fix drift
```
## Commands
| Command | What it does |
|---|---|
| `install [services]` | Install packages, create `/opt//tools` dirs (conventional perms), create the `hzsvn`/`hzgit` groups, write the drop-in(s). No services = all. After `install trac` it runs `test` automatically (skip with `--no-test`). |
| `uninstall ` | Remove a service's drop-in (and, for trac, unload its interpreter) plus hzforge's own files for it (shim, egg cache, wandisco repo file). **Never** removes packages, the `hzsvn`/`hzgit` groups, or repo data. |
| `doctor [services]` | Read-only diagnosis; exits non-zero on FAIL. Service checks scope to the request; global checks (`configtest`, interpreter state) always run. |
| `repair [services]` | Diagnose, then re-assert the requested services and fix drift, then validate + reload/restart. |
| `test [services]` | For each configured service, create a throwaway, uniquely-named project, verify it serves over HTTP (trac `…/wiki`, svn `…/svn/`, git `…/info/refs`) → 200, then remove it. Self-contained (no MySQL/forge provisioning; svn/git get a temporary self-test route). Exits non-zero on failure. |
### Install options
| Option | Default | Notes |
|---|---|---|
| `--trac-handler {mod_wsgi,mod_python}` | `mod_wsgi` | Exactly one interpreter is loaded. |
| `--svn-source {wandisco,appstream}` | `wandisco` | `subversion`+`mod_dav_svn` source; `subversion-python` always from hubzero. |
| `--ldap-url/--ldap-binddn/--ldap-bindpw` | auto-detect | Trac `/login` auth; read from `svn.conf` if omitted. |
| `--ldap-bindpw-file` | — | Read the bind password from a root-only file (avoids exposing it in the process list). |
| `--force-pip` | off | Reinstall Trac even if importable. |
Common: `--hub ` (auto-detected), `--dry-run`, `--no-restart`.
## How it works
- **No carve-out for alias handlers.** `WSGIScriptAliasMatch` (mod_wsgi Trac) and
`ScriptAliasMatch` (git) self-divert at translate-name, before the CMS rewrite.
`mod_dav_svn` and mod_python Trac use ``, so the drop-in shields those
paths with a vhost-scope `RewriteRule … - [END]`.
- **WSGI shim** (`/opt/trac/wsgi/hubtrac.wsgi`) re-splits `SCRIPT_NAME`/`PATH_INFO`
and selects the env — the mod_wsgi replacement for `PythonOption
TracUriRoot`.
- **Restart vs reload** is decided by comparing the running httpd's loaded modules
(`/proc//maps`) against what's enabled on disk; full restart only when the
interpreter set must change. With systemd it uses `systemctl`; without it (a
container/chroot) it drives `httpd -k` directly — EL8's `apachectl` always defers
`start`/`restart`/`graceful` to systemctl — and first creates the `/run/httpd`
runtime dir that `systemd-tmpfiles` would otherwise provide.
- **Trac ↔ Subversion are decoupled** — Trac runs without the repo browser;
the browser is auto-enabled only when the svn service is installed.
See [architecture](https://hubzero.github.io/hzforge/reference/architecture/) for
the full picture.
## Requirements
- Rocky/RHEL 8, Apache 2.4, Python 2.7 (for the Trac stack) and Python 3.6+ (to run
hzforge — it targets RHEL 8's stock `python3`, 3.6). Run as root.
- The `hubzero` yum repo (`hubzero-trac-mysqlauthz`, `subversion-python`);
for `--svn-source wandisco`, access to
`opensource.wandisco.com`; for the mod_wsgi handler, PyPI access.
## License
MIT — see [LICENSE.md](LICENSE.md). Copyright © 2026 Purdue University.