Metadata-Version: 2.2
Name: bisos.geneweb
Version: 0.1
Summary: bisos.geneweb: GeneWeb Genealogy via BISOS Capability Bundles
Author: Mohsen Banan
Author-email: libre@mohsen.1.banan.byname.net
Maintainer: Mohsen Banan
Maintainer-email: libre@mohsen.1.banan.byname.net
License: AGPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: bisos
Requires-Dist: bisos.b
Requires-Dist: bisos.banna
Requires-Dist: bisos.basics
Requires-Dist: bisos.capability
Requires-Dist: bisos.common
Requires-Dist: bisos.csPlayer
Requires-Dist: bisos.csSeed
Requires-Dist: bisos.debian
Requires-Dist: bisos.dnsCap
Requires-Dist: bisos.sbom
Requires-Dist: bisos.webCap
Requires-Dist: setuptools==75.8.0
Requires-Dist: wheel==0.38.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: license
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: summary

=============================================================
bisos.geneweb: GeneWeb Genealogy via BISOS Capability Bundles
=============================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.geneweb* is a BISOS package for running
`GeneWeb <https://geneweb.tuxfamily.org>`__, genealogy software, on a
BISOS host: its web server, ``gwd``, as a BISOS Capability Bundle
(CBS/CBM) of ``systemd``-planted Command Services, browsable as
``http://geneweb.here``, with an empty ``demo`` base so
``http://geneweb.here/demo`` works out of the box.

It is small (21 MB with 2 workers) and is enabled in the rawBisosCbm
set, with the raw platform as its real home (see
``bxGenesis/start/rawBisosCBMs/README.org``).

Package Documentation At Github
===============================

The information below is a subset of the full of documentation for this
bisos-pip package. More complete documentation is available at:
https://github.com/bisos-pip/geneweb-cs

.. _table-of-contents:

Table of Contents TOC
=====================

-  `Overview <#overview>`__
-  `Package Documentation At
   Github <#package-documentation-at-github>`__
-  `The BISOS GeneWeb Model <#the-bisos-geneweb-model>`__
-  `The Wizard Password <#the-wizard-password>`__
-  `What Gets Installed, and Where <#what-gets-installed-and-where>`__
-  `The 3 sboms and the Unit <#the-3-sboms-and-the-unit>`__
-  `Installation <#installation>`__
-  `Usage <#usage>`__

   -  `Materialization <#materialization>`__
   -  `Bases: Create, Import, Export <#bases-create-import-export>`__
   -  `Day-to-Day Admin:
      ``genewebAdmin.cs`` <#day-to-day-admin-genewebadmincs>`__

-  `Key Files <#key-files>`__
-  `Part of BISOS — ByStar Internet Services Operating
   System <#part-of-bisos--bystar-internet-services-operating-system>`__
-  `Documentation and Blee-Panels <#documentation-and-blee-panels>`__
-  `Support <#support>`__
-  `Planned Improvements <#planned-improvements>`__

   -  `Move to a final 7.1 release when one is published (with its
      digest) <#move-to-a-final-71-release-when-one-is-published-with-its-digest>`__
   -  `The "secure it" layer: real passwords, HTTPS, listening beyond
      loopback <#the-secure-it-layer-real-passwords-https-listening-beyond-loopback>`__
   -  `gwsetup, if it gains an option to bind an
      address <#gwsetup-if-it-gains-an-option-to-bind-an-address>`__
   -  `Plant the CBM leaf in bro\ rawBisos
      (``sys/cbm/collective/hereWeb/geneweb/``),
      enabled <#plant-the-cbm-leaf-in-bro_rawbisos-syscbmcollectiveherewebgeneweb-enabled>`__

The BISOS GeneWeb Model
=======================

``bisos.geneweb`` packages GeneWeb 7.1.0-beta2 as a hereWeb CBS/CBM, on
the pattern of the other CBM packages (the ``cbm-package-authorship``
skill): one module of facts (``genewebInfo.py``), a pinned and
checksummed upstream release, config written only when absent, a
read-only ``driftCheck``, a server sbom and a usage sbom joined only by
the CBS.

-  **The release.** Debian 13 does not package GeneWeb. The upstream
   Linux zip (59 MB; 171 MB unpacked) is pinned with the SHA-256 GitHub
   records for it. 7.1.0-beta2 (2025-12-25) is the newest release and
   the only one with a published digest. It is named a beta. GeneWeb is
   OCaml: its binaries need only ``libgmp10`` beyond libc.
-  **gwd only.** ``gwsetup``, GeneWeb's setup web UI, is not run: it
   cannot bind an address and would listen on every interface. Bases are
   created with the command-line tools (below).
-  **Read-only distribution.** ``gwd`` runs from the root-owned unpacked
   zip and writes only to its bases and work directories.
-  **Earlier BISOS GeneWeb.** ``/bisos/asc/geneweb6`` and ``geneweb7``
   hold older bash-ICM installers (an unpinned 2022 zip); this package
   replaces them for the CBM pattern.

**As of 2026-10-16 it is materialized on one host** (Debian 13): the
unit active; a GEDCOM imported with ``ged2gwb``, browsed through
``http://geneweb.here``, and exported back with ``gwb2ged``; editing
refused without the wizard password and allowed with it; ``driftCheck``
agrees.

The Wizard Password
===================

GeneWeb has no user names: a *wizard* password lets you edit, a *friend*
password lets you see private data. Following the rawBisos convention
(the password is the service's name), the wizard password is
**geneweb**; there is no friend password, and public pages need no
login. It is passed to ``gwd`` with ``-wizard`` (visible in ``ps``).
Insecure by design; securing a host is a separate layer.

What Gets Installed, and Where
==============================

+------------------------+------------------------+------------------+
| What                   | Where                  | Owner            |
+========================+========================+==================+
| The ``geneweb``        | uid/gid 508, from      | —                |
| account                | bisos.banna            |                  |
+------------------------+------------------------+------------------+
| GeneWeb 7.1.0-beta2    | ``/opt/geneweb         | root             |
|                        | /geneweb-7.1.0-beta2`` |                  |
+------------------------+------------------------+------------------+
| Active GeneWeb         | ``                     | root             |
|                        | /opt/geneweb/current`` |                  |
|                        | -> the above           |                  |
+------------------------+------------------------+------------------+
| gwd flags              | ``                     | root:geneweb 640 |
|                        | /etc/default/geneweb`` |                  |
|                        | (``ARGS=``)            |                  |
+------------------------+------------------------+------------------+
| The bases              | ``/v                   | geneweb (750)    |
|                        | ar/lib/geneweb/bases`` |                  |
|                        | (``demo`` at first)    |                  |
+------------------------+------------------------+------------------+
| gwd's work directory   | `                      | geneweb          |
|                        | `/var/lib/geneweb/wd`` |                  |
+------------------------+------------------------+------------------+

``ARGS`` sets
``-a 127.0.0.1 -p 24017 -n_workers 2 -lang en -wizard geneweb -log -``
(the log goes to journald). The EnvironmentFile is written only when
absent; the ``demo`` base is created once.
``genewebAdmin.cs -i driftCheck`` reports the EnvironmentFile, the unit,
the link and the demo base.

The 3 sboms and the Unit
========================

+---------------------------+----------------------------+----------+
| sbom                      | Installs                   | Pulls in |
+===========================+============================+==========+
| ``geneweb-sbom.pcs``      | curl, unzip, libgmp10;     | nothing  |
|                           | account; the zip; config   |          |
+---------------------------+----------------------------+----------+
| ``genewebUsage-sbom.pcs`` | the same zip, for the      | nothing  |
|                           | GEDCOM and base tools      |          |
+---------------------------+----------------------------+----------+
| ``genewebCbs-sbom.pcs``   | nothing of its own         | both     |
+---------------------------+----------------------------+----------+

GeneWeb has no separate client: one uses it in a browser. Its usage side
is its tools — ``ged2gwb``, ``gwb2ged``, ``gwc``, ``gwu`` — for
preparing and converting family trees on any host. They ship only in the
zip, so both sboms unpack the same pinned zip (whichever runs first).

The unit, ``geneweb-sysd.pcs``, runs ``gwd $ARGS`` as ``User=geneweb``.
Port 24017 and ``geneweb.here`` (127.0.22.119) come from
``bisos.banna``.

Installation
============

The sources are at https://github.com/bisos-pip/geneweb and the package
is at https://pypi.org/project/bisos.geneweb. Install with
``pip install bisos.geneweb``, or with ``pipx install bisos.geneweb``
for the commands only: ``genewebAdmin.cs``, ``quickGeneweb.cs``,
``geneweb-assemble.cs``, ``cbmProc-geneweb.spcs``. The planted ``.pcs``
files are invoked from ``py3/bin/``.

Usage
=====

Materialization
---------------

.. code:: bash

   geneweb-sbom.pcs -i sbom_fullUpdate          # the server only
   genewebUsage-sbom.pcs -i sbom_fullUpdate     # the tools only
   geneweb-cbs.pcs -i cbs_materialize           # both sboms + unit + assemble

Then browse ``http://geneweb.here/demo``.

Bases: Create, Import, Export
-----------------------------

Run the tools as the ``geneweb`` account, in the bases directory. A new
base is served at once, with no restart, as
``http://geneweb.here/<name>``.

.. code:: bash

   cd /var/lib/geneweb/bases
   sudo -u geneweb /opt/geneweb/current/gw/gwc -o family                       # an empty base
   sudo -u geneweb /opt/geneweb/current/gw/ged2gwb /tmp/family.ged -o family   # GEDCOM -> base
   sudo -u geneweb /opt/geneweb/current/gw/gwb2ged family -o /tmp/family.ged   # base -> GEDCOM

Day-to-Day Admin: ``genewebAdmin.cs``
-------------------------------------

.. code:: bash

   genewebAdmin.cs -i hostInfo        # fqdn, listener, wizard password, paths
   genewebAdmin.cs -i servicesInfo    # links for operating the unit, dns and vhost
   genewebAdmin.cs -i basesInfo       # create, import, export, list bases
   genewebAdmin.cs -i driftCheck      # read-only: env file, unit, link, demo base vs genewebInfo
   quickGeneweb.cs                    # the flat cheat sheet

Key Files
=========

-  ``py3/bisos/geneweb/genewebInfo.py`` — the single source of facts:
   the pinned release, paths, port, wizard password, the demo base, the
   generators and the install scripts (``zipSetupScript``, the zip form
   of the tarball helper).
-  ``py3/bin/geneweb-cbs.pcs``, ``cbmProc-geneweb.spcs`` — the CBS and
   the CBM pointer.
-  ``py3/bin/geneweb-sbom.pcs``, ``genewebUsage-sbom.pcs``,
   ``genewebCbs-sbom.pcs`` — the three sboms.
-  ``py3/bin/geneweb-sysd.pcs`` — the unit.
-  ``py3/bin/geneweb-assemble.cs``, ``geneweb-here-dns.pcs``,
   ``geneweb-wvd.pcs`` — assembly.
-  ``py3/bin/genewebAdmin.cs``, ``quickGeneweb.cs`` — admin CS and cheat
   sheet.
-  ``py3/tests/verify.sh`` — smoke test of every command and of
   ``genewebInfo``'s invariants.

Part of BISOS — ByStar Internet Services Operating System
=========================================================

Layered on top of Debian, **BISOS** (By\* Internet Services Operating
System) is a unified and universal framework for developing both
internet services and software-service continuums that use internet
services. See `Bootstrapping ByStar, BISOS and
Blee <https://github.com/bxGenesis/start>`__ for getting started with
BISOS.

**BISOS** is a foundation for **The Libre-Halaal ByStar Digital
Ecosystem** which is described as a cure for losses of autonomy and
privacy in a book titled: `Nature of
Polyexistentials <https://github.com/bxplpc/120033>`__

*bisos.geneweb* is part of BISOS. It is a standalone package that can be
used independently of the full BISOS environment.

Documentation and Blee-Panels
=============================

bisos.geneweb is part of the ByStar Digital Ecosystem
http://www.by-star.net. Its primary documentation is in the form of
Blee-Panels, in ``./panels``; see
`file:./panels/bisos.geneweb/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.geneweb/_nodeBase_/fullUsagePanel-en.org>`__
for a starting point. It is best developed with
`Blee <https://github.com/bx-blee>`__, the *By\* BISOS Libre-Halaal
Emacs Environment*.

Support
=======

| For support, criticism, comments and questions; please contact the
  author/maintainer
| `Mohsen Banan <http://mohsen.1.banan.byname.net>`__ at:
  http://mohsen.1.banan.byname.net/contact

Planned Improvements
====================

.. _move-to-a-final-7.1-release-when-one-is-published-with-its-digest:

TODO Move to a final 7.1 release when one is published (with its digest)
------------------------------------------------------------------------

.. _the-secure-it-layer-real-passwords-https-listening-beyond-loopback:

TODO The "secure it" layer: real passwords, HTTPS, listening beyond loopback
----------------------------------------------------------------------------

.. _gwsetup-if-it-gains-an-option-to-bind-an-address:

TODO gwsetup, if it gains an option to bind an address
------------------------------------------------------

.. _plant-the-cbm-leaf-in-brorawbisos-syscbmcollectiveherewebgeneweb-enabled:

TODO Plant the CBM leaf in bro\ :sub:`rawBisos` (``sys/cbm/collective/hereWeb/geneweb/``), enabled
--------------------------------------------------------------------------------------------------
