usage.md

Usage

Run as root (sudo). Services are positional (space- or comma-separated). A bare hzforge prints help.

See Requirements for host, Python, package, and network prerequisites before installing, and Manual installation for the step-by-step by-hand procedure (what these commands automate) for each handler/service set.

sudo python3 hzforge.py install                          # all services
sudo python3 hzforge.py install trac                     # one service
sudo python3 hzforge.py install svn git gitExternal trac
sudo python3 hzforge.py install trac --trac-handler mod_python
sudo python3 hzforge.py install trac --python py36       # Py3.6 + Trac 1.6 (Stage 2)
sudo python3 hzforge.py uninstall git                    # stop serving git (packages/data kept)
sudo python3 hzforge.py doctor                           # diagnose all configured
sudo python3 hzforge.py doctor git                       # diagnose one service
sudo python3 hzforge.py repair                           # fix drift
sudo python3 hzforge.py repair trac
sudo python3 hzforge.py test                             # throwaway project per configured service, verify, remove
sudo python3 hzforge.py test svn git                     # only the named services
sudo python3 hzforge.py upgrade-trac                     # per-env legacy-macro cleanup + trac.ini sanity
sudo python3 hzforge.py enable-cmsauth hzforgetest       # switch an env from LDAP to HUBzero CMS SSO

Preview any command without changing anything:

sudo python3 hzforge.py install --dry-run

Commands

install [services]

Install packages, create /opt/<svc>/tools dirs (conventional perms), create the hzsvn/hzgit groups, and write the per-service drop-in(s). No services = all four. Consolidates a legacy standalone trac.conf into the trac drop-in. On a host without systemd (a container or chroot) it also creates the /run/httpd runtime dir that httpd -k start needs, since systemd-tmpfiles isn't there to make it. After installing trac it runs the test self-check automatically (skip with --no-test).

uninstall <services>

Remove a service's drop-in (and, for trac, unload its interpreter module) plus the helper files hzforge created for it — for trac the WSGI shim and egg cache, for svn the wandisco repo file. Never removes packages, the hzsvn/hzgit groups, or repository data under /opt/<svc>/tools (only the config/serving is torn down). A requested service that isn't currently configured is reported and skipped; if none of the requested services are configured, the running server is left untouched.

doctor [services]

Read-only diagnosis; exits non-zero if anything is FAIL. Service-specific checks are scoped to the requested services; global checks always run: apachectl configtest, running-vs-on-disk interpreter state, a stray legacy trac.conf, the service-control mechanism (systemd vs httpd -k), presence of the /run/httpd runtime dir on non-systemd hosts, and whether httpd is actually active.

repair [services]

Diagnose, then re-assert the requested (configured) services — fixing missing shim/dirs, file permissions, and module state — then validate and reload/restart. repair git is isolated to git; it won't touch trac.

test [services]

End-to-end self-check per service. For each requested (configured) service it creates a throwaway, uniquely-named project, fetches it over the hub's own vhost, asserts a 200, then removes it. No services = all configured.

Service	Resource created	URL checked	Pass signal
trac	Trac env under /opt/trac/tools/	/tools/<name>/wiki	Trac wiki page
svn	repo via svnadmin create under /opt/svn/tools/	/tools/<name>/svn/	mod_dav_svn listing
git / gitExternal	bare repo under /opt/<svc>/tools/<name>.git	…/git/<name>/info/refs?service=git-upload-pack	git-http-backend advertisement

It needs no MySQL/forge provisioning. mod_wsgi trac is served by hzforge's generic WSGI route (no config change); svn, git, and mod_python trac need a per-resource route, so a temporary self-test drop-in (00-forge-selftest.conf) is added and removed around the checks (graceful reload). Both Trac handlers are self-testable. Exits non-zero on failure (handy for CI). The just-installed services are tested automatically at the end of install (skip with --no-test).

upgrade-trac [envs]

Per-env Trac housekeeping under /opt/trac/tools/. Today it (1) ensures the universal hubzero_macros.* plugin is enabled in each env's trac.ini ([components] text-surgery, idempotent — and done before any disable so there's no rendering gap), then (2) disables that env's legacy per-env plugins/image.py / link.py copies (renamed to .disabled) now that the system-wide hubzero-trac-macros wheel serves the same macros. No envs = all configured envs. A graceful httpd reload follows if anything changed.

enable-cmsauth <envs> [--install-wheel PATH]

Switch one or more Trac envs from Apache LDAP-Basic auth to HUBzero CMS SSO (the hubzero-trac-cmsauth plugin). Per env it sets [components] hubzero_cmsauth.* = enabled + trac.web.auth.LoginModule = disabled in trac.ini, and extends the LDAP <LocationMatch> negative-lookahead in the trac drop-in to skip that env. --install-wheel PATH first installs the cmsauth wheel into every interpreter's site-packages (recommended for the first env on a fresh host); otherwise the plugin is verified importable before any change. Env names must be [A-Za-z0-9_-]+ (they go verbatim into the Apache carve-out regex). Ends with apachectl configtest + graceful reload.

Options (install)

Option	Default	Notes
--python {py27,py36}	py27	The install matrix. py27 = Python 2.7 + Trac 1.0.x; py36 = Rocky 8 stock Python 3.6 + Trac 1.6 (Stage 2). Picks the interpreter, pip, Trac spec, mod_wsgi source, and svn module stream. py36 + mod_python is rejected (mod_python is Py2-only).
--trac-handler {mod_wsgi,mod_python}	mod_wsgi	Exactly one interpreter is loaded. mod_python only valid with --python py27.
(svn source — no flag)	AppStream module	subversion + mod_dav_svn always come from the system AppStream subversion module; the stream is picked from --python: py27→subversion:1.10, py36→subversion:1.14 (first stream shipping python3-subversion). subversion-python (py27 SWIG bindings) comes from hubzero-julian; py36 uses python3-subversion from the 1.14 module. A host still on the old wandisco RPMs is auto-migrated to AppStream on the next install svn (clean cutover: dnf remove + module reset + reinstall). wandisco is no longer used — there is no --svn-source flag.
--trac-spec	per --python	py27→Trac==1.0.14 (DB schema 26 line, no upgrade), py36→Trac>=1.6,<1.7. Explicit value wins.
--modwsgi-spec	py27 only	py27→mod_wsgi==4.9.4 (last Py2-capable, pip-built); py36 uses the python3-mod_wsgi RPM (this option is moot there).
--ldap-url / --ldap-binddn / --ldap-bindpw	auto-detect	for the Trac /login auth block; read from the existing svn.conf if not given. A bind password containing a newline or " is rejected (would inject Apache directives).
--ldap-bindpw-file	—	read the bind password from a root-only file instead of --ldap-bindpw (which is visible in the process list). A group/other-readable file is a fatal error.
--force-pip	off	reinstall Trac even if importable.

Common to all commands: --hub <name> (auto-detected from sites.d), --dry-run, --no-restart. --install-wheel PATH is specific to enable-cmsauth.

Exit codes

• doctor exits 0 when there are no FAIL findings, 1 otherwise — handy in CI or monitoring.
• Other commands exit non-zero on a hard error (e.g. configtest failure, after which the running server is left untouched).

Safety

• apachectl configtest runs before any reload/restart; on failure hzforge aborts without touching the running server.
• --dry-run previews every action; --no-restart stages changes without applying.
• uninstall never removes packages, the hzsvn/hzgit groups, or repository data under /opt/<svc>/tools.