Metadata-Version: 2.2
Name: bisos.devpi
Version: 0.1
Summary: bisos.devpi: A Minimal devpi Python Package Index 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.devpi: A Minimal devpi Python Package Index via BISOS Capability Bundles
==============================================================================

.. contents::
   :depth: 3
..

Overview
========

*bisos.devpi* is a BISOS package for running
`devpi <https://devpi.net>`__ — ``devpi-server`` with its web UI,
``devpi-web`` — on a BISOS host, as a BISOS Capability Bundle (CBS/CBM)
of ``systemd``-planted Command Services, browsable as
``http://devpi.here``.

In a rawBisosCbm materialization devpi is **minimal**: no PyPI mirror
(``devpi-init --no-root-pypi``) and 4 threads. That is 81 MB of memory
instead of about 500 MB with the mirror, which indexes all of PyPI's
project names at start. A real devpi, with its mirror, typically runs in
a dedicated VM and is configured there (see
``bxGenesis/start/rawBisosCBMs/README.org``).

A planted pointer leaf (``cbmProc.spcs``, at
``sys/cbm/collective/hereWeb/devpi/``) subprocess-invokes the Capability
Bundle Specification, ``devpi-cbs.pcs``: the sboms, two units (``devpi``
and the ``devpi-accounts`` oneshot), and the assembly step
(``devpi.here`` dns entry and nginx vhost).

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/devpi-cs

.. _table-of-contents:

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

-  `Overview <#overview>`__
-  `Package Documentation At
   Github <#package-documentation-at-github>`__
-  `The BISOS devpi Model <#the-bisos-devpi-model>`__
-  `The Logins and the Index <#the-logins-and-the-index>`__
-  `Why an Isolated venv <#why-an-isolated-venv>`__
-  `What Gets Installed, and Where <#what-gets-installed-and-where>`__
-  `The 3 sboms and the 2 Units <#the-3-sboms-and-the-2-units>`__
-  `Installation <#installation>`__
-  `Usage <#usage>`__

   -  `Materialization <#materialization>`__
   -  `Using the Index <#using-the-index>`__
   -  `Day-to-Day Admin:
      ``devpiAdmin.cs`` <#day-to-day-admin-devpiadmincs>`__

-  `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>`__

   -  `The "secure it" layer: real passwords, HTTPS (no more
      –trusted-host), beyond
      loopback <#the-secure-it-layer-real-passwords-https-no-more---trusted-host-beyond-loopback>`__
   -  `Back into ``asc`` once devpi-server accepts the setuptools
      there <#back-into-asc-once-devpi-server-accepts-the-setuptools-there>`__
   -  `Plant the CBM leaf in bro\ rawBisos
      (``sys/cbm/collective/hereWeb/devpi/``),
      enabled <#plant-the-cbm-leaf-in-bro_rawbisos-syscbmcollectiveherewebdevpi-enabled>`__

The BISOS devpi Model
=====================

``bisos.devpi`` packages devpi-server 6.20.3 and devpi-web 5.1.1 as a
hereWeb CBS/CBM, on the pattern of ``bisos.kafka``,
``bisos.prometheus``, ``bisos.grafana`` and ``bisos.pypiserver`` (the
``cbm-package-authorship`` skill): one module of facts
(``devpiInfo.py``), exact hash-pinned versions, config written only when
absent, a read-only ``driftCheck``, a server sbom and a usage sbom
joined only by the CBS. It is for the rawBisos layer: minimal,
convenient and insecure by design.

**As of 2026-10-16 it is materialized on one host** (Debian 13): both
units active, uploads with twine and with devpi-client, installs with
pip and browsing in devpi-web verified through ``http://devpi.here``,
``driftCheck`` agrees.

The Logins and the Index
========================

-  **root / devpi** — devpi's superuser, set by
   ``devpi-init --root-passwd``.
-  **admin / devpi** — the rawBisos convention (user ``admin``, password
   the service's name), the owner of the index **``admin/dev``**: a
   volatile stage with no bases (uploads only, no mirror).

Both are created at materialization: ``root`` by ``devpi-init`` (once),
``admin`` and ``admin/dev`` by the ``devpi-accounts`` oneshot unit,
after ``devpi`` starts. They cannot be created in the assemble step:
``cbs_materialize`` runs sbom, then assemble, then the units, so the
server is not up during assemble. ``--restrict-modify root,admin`` lets
only these two create users and indexes; devpi's default lets anyone.
Insecure by design; securing a host is a separate layer on top.

Why an Isolated venv
====================

Python programs go in BISOS's shared venv, ``/bisos/venv/asc``, unless
they have been shown not to work there. devpi-server 6.20.3 requires
``setuptools<=81`` (and pyramid 2.1 ``<82``); ``asc`` has setuptools
84.0.0, and installing devpi there would downgrade it. So devpi runs
from ``/bisos/venv/isolated/devpiServer``, with all 55 packages of its
resolved set pinned with their sha256 (each checked against PyPI's
published digest; installed with ``pip --require-hashes
--no-deps``). Several wheels are binary: the set covers amd64 with
Python 3.13. When devpi-server accepts the setuptools in ``asc``, it
moves back and this venv is deleted.

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

Every fact below lives in one place, ``py3/bisos/devpi/devpiInfo.py``.

+-------------------------+-------------------------+----------------+
| What                    | Where                   | Owner          |
+=========================+=========================+================+
| The ``devpi`` account   | uid/gid 507, from       | —              |
|                         | bisos.banna             |                |
+-------------------------+-------------------------+----------------+
| devpi-server,           | ``/bisos/venv           | the venv owner |
| devpi-web, set          | /isolated/devpiServer`` |                |
+-------------------------+-------------------------+----------------+
| devpi-client (usage     | ``                      | pipx           |
| side)                   | /bisos/pipx/bin/devpi`` |                |
+-------------------------+-------------------------+----------------+
| Server flags            | ``/etc/default/devpi``  | root:devpi 640 |
|                         | (``ARGS=``)             |                |
+-------------------------+-------------------------+----------------+
| The accounts script     | ``/etc/de               | root:devpi 640 |
|                         | vpi/devpi-accounts.py`` |                |
+-------------------------+-------------------------+----------------+
| Server state            | ``                      | devpi 750      |
|                         | /var/lib/devpi/server`` |                |
+-------------------------+-------------------------+----------------+

``ARGS`` sets
``--host 127.0.0.1 --port 24015 --threads 4 --outside-url http://devpi.here
--restrict-modify root,admin``. The EnvironmentFile is written only when
absent; the accounts script is code and is rewritten by every sbom run.
``devpiAdmin.cs -i driftCheck`` reports the EnvironmentFile, the
accounts script, the initialized server directory, both units and all 55
pins.

The 3 sboms and the 2 Units
===========================

+-------------------------+----------------------------+----------+
| sbom                    | Installs                   | Pulls in |
+=========================+============================+==========+
| ``devpi-sbom.pcs``      | account, isolated venv,    | nothing  |
|                         | config, devpi-init         |          |
+-------------------------+----------------------------+----------+
| ``devpiUsage-sbom.pcs`` | devpi-client 7.3.0,        | nothing  |
|                         | through pipx               |          |
+-------------------------+----------------------------+----------+
| ``devpiCbs-sbom.pcs``   | nothing of its own         | both     |
+-------------------------+----------------------------+----------+

+------------------------+------------------------+------------------+
| Unit                   | Runs                   | After            |
+========================+========================+==================+
| ``devpi-sysd.pcs``     | ``devpi-server $ARGS`` | network          |
|                        | (waitress inside)      |                  |
+------------------------+------------------------+------------------+
| ``dev                  | oneshot:               | devpi, Requires= |
| pi-accounts-sysd.pcs`` | ``pyth                 |                  |
|                        | on devpi-accounts.py`` |                  |
+------------------------+------------------------+------------------+

Both run as ``User=devpi``; logs go to journald. Port 24015 and
``devpi.here`` (127.0.22.117) come from ``bisos.banna``.

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

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

Usage
=====

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

.. code:: bash

   devpi-sbom.pcs -i sbom_fullUpdate          # the server only
   devpiUsage-sbom.pcs -i sbom_fullUpdate     # the usage side only (devpi-client)
   devpi-cbs.pcs -i cbs_materialize           # both sboms + units + assemble

Using the Index
---------------

pip needs ``--trusted-host`` for an index on plain HTTP; every ``.here``
is HTTP.

.. code:: bash

   pip install --index-url http://devpi.here/admin/dev/+simple/ --trusted-host devpi.here <package>
   twine upload --repository-url http://devpi.here/admin/dev/ -u admin -p devpi dist/*
   /bisos/pipx/bin/devpi use http://devpi.here/admin/dev
   /bisos/pipx/bin/devpi login admin --password devpi
   /bisos/pipx/bin/devpi upload        # in a project

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

.. code:: bash

   devpiAdmin.cs -i hostInfo        # fqdn, listener, logins, venv, config/data paths
   devpiAdmin.cs -i servicesInfo    # links for operating the 2 units
   devpiAdmin.cs -i indexInfo       # pip, twine and devpi-client against admin/dev
   devpiAdmin.cs -i driftCheck      # read-only: config, accounts script, units, pins vs devpiInfo
   quickDevpi.cs                    # the flat cheat sheet

Key Files
=========

-  ``py3/bisos/devpi/devpiInfo.py`` — the single source of facts: the
   isolated venv and its hashed set (and why it is isolated), paths,
   port, logins, the generators of the EnvironmentFile and the accounts
   script, the install scripts, and the drift helpers.
-  ``py3/bin/devpi-cbs.pcs``, ``cbmProc-devpi.spcs`` — the CBS and the
   CBM pointer.
-  ``py3/bin/devpi-sbom.pcs``, ``devpiUsage-sbom.pcs``,
   ``devpiCbs-sbom.pcs`` — the three sboms.
-  ``py3/bin/devpi-sysd.pcs``, ``devpi-accounts-sysd.pcs`` — the two
   units.
-  ``py3/bin/devpi-assemble.cs``, ``devpi-here-dns.pcs``,
   ``devpi-wvd.pcs`` — assembly: dns and vhost.
-  ``py3/bin/devpiAdmin.cs``, ``quickDevpi.cs`` — admin CS and cheat
   sheet.
-  ``py3/tests/verify.sh`` — smoke test of every command and of
   ``devpiInfo``'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.devpi* is part of BISOS. It is a standalone package that can be
used independently of the full BISOS environment.

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

bisos.devpi 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.devpi/_nodeBase_/fullUsagePanel-en.org <./panels/bisos.devpi/_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
====================

.. _the-secure-it-layer-real-passwords-https-no-more-trusted-host-beyond-loopback:

TODO The "secure it" layer: real passwords, HTTPS (no more –trusted-host), beyond loopback
------------------------------------------------------------------------------------------

.. _back-into-asc-once-devpi-server-accepts-the-setuptools-there:

TODO Back into ``asc`` once devpi-server accepts the setuptools there
---------------------------------------------------------------------

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

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