commit a6cd7011bf079f59231aa8a6950db70f6338d1a3
parent 836cfb2029b0a3ce08102e95757ef06ed2cdc25e
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Mon, 25 May 2026 12:33:53 +0200
start paivana manual
Diffstat:
1 file changed, 167 insertions(+), 0 deletions(-)
diff --git a/taler-paivana-manual.rst b/taler-paivana-manual.rst
@@ -0,0 +1,167 @@
+..
+ This file is part of GNU TALER.
+
+ Copyright (C) 2026 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Martin Schanzenbach
+
+Paivana Operator Manual
+#######################
+
+Introduction
+============
+
+About Paivana
+-------------
+
+Paivana is an approach to implement paywalls using GNU Taler.
+
+For the seller, the Paivana design offers a scalable, cachable, static paywall
+with flexible payment options to sell access to digital assets. Aside from
+selling digital articles, Paivana can be used to protect servers against
+DDoS-attacks (say from botnets ignoring rate-limits), providing an alternative
+to Anubis.
+
+For buyers, Paivana offers all of the conveniences, privacy and security
+features of the GNU Taler system. Paivana paywalls are also suitable for
+agentic payments, as agents can easily be provisioned with access to a
+GNU Taler wallet enabling them to purchase digital goods and services
+while limiting the financial risk to the amount of money placed into the
+agent's wallet.
+
+About this manual
+-----------------
+
+This manual targets system administrators who want to install,
+operate or integrate Paivana-based paywalls. To report issues
+or learn about known limitations, please check our
+`bug tracker <https://bugs.taler.net>`__.
+
+
+Overview
+--------
+
+At this point, there are several integration options for Paivana-style
+paywalls:
+
+- Using the Paivana reverse proxy: This is a generic solution suitable
+ for any HTTP-based service. By placing the Paivana reverse proxy
+ before the existing HTTP service, clients can be required to pay before
+ accessing the service, without requiring any changes to the service
+ itself. A disadvantage is that it can be difficult to make
+ the Paivana reverse proxy fit into the look-and-feel of the site,
+ and that the configuration of payment rules must be done separate
+ from the actual content of the site.
+- Using the Drupal Paivana extension: This extension works basically
+ for any Drupal site, making it easy to keep the overall look-and-feel
+ of the site. Prices can be configured per article within the site
+ itself. The extension only works for Drupal.
+- Using the Wordpress Paivana extension: This extension works basically
+ for any Wordpress site, making it easy to keep the overall look-and-feel
+ of the site. Prices can be configured per article within the site
+ itself. The extension only works for Wordpress.
+
+In all cases, Paivana additionally requires access to a GNU Taler
+merchant backend. It is assumed that such a backend is available
+and configured to process orders. When setting up the respective
+Paivana service, you must have the base URL, username and password
+of the selected merchant backend at hand.
+
+
+Paivana-httpd
+=============
+
+This chapter documents the installation and operation of the Paivana
+reverse proxy.
+
+
+Installing from source
+----------------------
+
+The following instructions will show how to install libgnunetutil and
+the core GNU Taler libraries from source.
+
+The package sources can be find in our
+`download directory <http://ftpmirror.gnu.org/taler/>`__.
+
+GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format.
+The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match.
+Exceptions to this general rule are documented in the release notes. For
+example, paivana-httpd 1.6.0 should be compatible with Taler exchange 1.6.x as
+the MAJOR version matches. A MAJOR version of 0 indicates experimental
+development, and you are expected to always run all of the *latest* releases
+together (no compatibility guarantees).
+
+First, the following packages need to be installed before we can compile the
+backend:
+
+- Golang >= 1.19
+
+- taler-merchant >= 1.6
+
+
+
+Installing the directory binary packages on Debian
+--------------------------------------------------
+
+.. include:: frags/installing-debian.rst
+
+To install paivana-httpd can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install paivana-httpd
+
+Note that the package does not perform any configuration work except for
+setting up the various users and the systemd service scripts. You still must
+configure the HTTP request routing.
+
+
+Installing the GNU Taler binary packages on Ubuntu
+--------------------------------------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the Taler exchange, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install paivana-httpd
+
+Note that the package does not perform any configuration work except for
+setting up the various users and the systemd service scripts. You still must
+configure the HTTP request routing.
+
+
+Configuration
+-------------
+
+FIXME!
+
+
+Drupal integration
+==================
+
+This chapter documents the installation and operation of the
+Drupal Paivana module.
+
+FIXME!
+
+Wordpress integration
+=====================
+
+This chapter documents the installation and operation of the
+Wordpress Paivana module.
+
+FIXME!
