commit 40face1f4d29441d697676702e0ef23a6fdcea7e
parent de97406083f55bf7a52ebf72103e9f581c730706
Author: Antoine A <>
Date: Tue, 25 Nov 2025 11:49:44 +0100
depolymerization: improve manual
Diffstat:
2 files changed, 147 insertions(+), 16 deletions(-)
diff --git a/depolymerization/bitcoin-manual.rst b/depolymerization/bitcoin-manual.rst
@@ -21,13 +21,38 @@ Bitcoin Depolymerizer Setup Manual
depolymerizer-bitcoin is a bitcoin blockhain Taler adapter.
-In this manual, we explain how to setup an adapter.
+This manual targets system administrators who want to install and
+operate a Bictoin GNU Taler Depolymerizer
+
+In this manual, we explain how to setup a depolymerizer.
.. contents:: Table of Contents
:local:
-Installing Bitcoin Depolymerizer
-================================
+Installation of the Bitcoin Depolymerizer
+=========================================
+
+Installing on Debian
+--------------------
+
+.. include:: frags/installing-debian.rst
+
+To install the depolymerizer, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install bitcoin-depolymerizer
+
+Installing on Ubuntu
+--------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the depolymerizer, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install bitcoin-depolymerizer
Building from source
--------------------
@@ -39,19 +64,13 @@ Bitcoin Depolymerizer belongs to the Depolymerization project, and can be downlo
$ git clone git://git.taler.net/depolymerization
$ cd depolymerization
-You will need the latest version of the rust stable toolchain:
+You will need the latest version of the rust stable toolchain and a C toolchain:
.. code-block:: console
- $ sudo apt install rustup
+ $ sudo apt install rustup build-essential
$ rustup toolchain install stable
-And a working C toolchain:
-
-.. code-block:: console
-
- $ sudo apt install build-essential
-
Then from top-level run:
.. code-block:: console
@@ -65,9 +84,9 @@ To install the depolymerizer as a Debian/Ubuntu package with an automated secure
.. code-block:: console
- $ cargo install cargo-deb
+ $ sudo apt install debhelper
$ make deb
- $ sudo dpkg -i target/debian/*.deb
+ $ sudo dpkg -i ../depolymerizer-bitcoin*.deb
If the previous steps succeeded, the ``depolymerizer-bitcoin`` command should be found in the $PATH.
@@ -83,8 +102,39 @@ To install the depolymerizer binaries and default configuration localy run:
If the previous steps succeeded, the ``depolymerizer-bitcoin`` command should be found in the $PATH.
-Installing bitcoind
-===================
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *depolymerizer-bitcoin* package will create several system users
+to compartmentalize different parts of the system:
+
+* ``depolymerizer-bitcoin-httpd``: runs the HTTP daemon with the API logic.
+* ``depolymerizer-bitcoin-worker``: runs the worker daemon with the bitcoind node.
+* ``depolymerizer-bitcoin-node``: runs the bitcoind node daemon interacting.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+
+The depolymerizer setup uses the following system groups:
+
+* ``depolymerizer-bitcoin-db``: group for all users with direct database access, specifically depolymerizer-bitcoin-httpd and depolymerizer-bitcoin-worker.
+* ``depolymerizer-bitcoin-cookie``: group for all users with access to the bicoind cookie file, specifically depolymerizer-bitcoin-worke and depolymerizer-bitcoin-node.
+
+The package will deploy systemd service files in
+``/usr/lib/systemd/system/`` for the various components:
+
+* ``depolymerizer-bitcoin-httpd.service``: adapter REST API.
+* ``depolymerizer-bitcoin-httpd.socket``: systemd socket activation for the HTTP daemon.
+* ``depolymerizer-bitcoin-worker.service``: worker daemon with the bitcoind node.
+* ``depolymerizer-bitcoin-node.service``: bitcoin node.
+* ``depolymerizer-bitcoin.target``: main target for the depolymerizer to be operational.
+
+The deployment creates the following key locations in the system:
+
+* ``/etc/depolymerizer-bitcoin/``: configuration files.
+* ``/run/depolymerizer-bitcoin/``: contains the UNIX domain sockets for inter-process communication (IPC).
+* ``/var/lib/bitcoind``: serves as the $HOME for depolymerizer-bitcoin-node and contains the bitcoind node data and cookie files.
+
+Installation of the Bitcoin node
+================================
You need to install bitcoind & bitcoin-cli yourself, you can install them from the `Bitcoin Core website <https://bitcoincore.org/en/download/>`_.
@@ -135,6 +185,39 @@ In another terminal check if the node is running:
$ bitcoin-cli getblockchaininfo
+Configuration Fundamentals
+==========================
+
+This chapter provides fundamental details about the adapter configuration.
+
+The configuration for all adapter components uses a single configuration file
+as entry point: ``/etc/depolymerizer-bitcoin/depolymerizer-bitcoin.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/depolymerizer-bitcoin/config.d``.
+These default files should never be modified.
+
+The default configuration ``depolymerizer-bitcoin.conf`` configuration file
+also includes all configuration files in ``/etc/depolymerizer-bitcoin/conf.d``.
+The settings from files in
+``conf.d`` are only relevant to particular components of an adapter, while
+``depolymerizer-bitcoin.conf`` contains settings that affect all adapter components.
+
+
+The directory ``/etc/depolymerizer-bitcoin/secrets`` contains configuration file snippets with
+values that should only be readable to certain users. They are included with the ``@inline-secret@``
+directive and should end with ``.secret.conf``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``depolymerizer-bitcoin config`` helper:
+
+
+.. code-block:: shell-session
+
+ # depolymerizer-bitcoin config dump --diagnostics
+
+.. include:: frags/configuration-format.rst
+
Bitcoin Depolymerizer Setup
===========================
@@ -384,6 +467,54 @@ this automatically:
Deployment
==========
+This chapter describes how to deploy the depolymerizer once the basic installation
+and configuration are completed.
+
+Serving
+-------
+
+The depolymerizer can serve HTTP over both TCP and UNIX domain socket.
+
+The following options are to be configured in the section ``[depolymerizer-bitcoin-httpd]``:
+
+- ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve
+ HTTP over a UNIX domain socket.
+
+- ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``.
+
+- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is
+ ``unix``.
+
+- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask
+ for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such
+ a way that your depolymerizer has permissions to access the UNIX domain
+ socket. The default (660) assumes that the reverse proxy is a member of
+ the group under which the depolymerizer HTTP server is running.
+
+Reverse Proxy Setup
+-------------------
+
+By default, the ``depolymerizer-bitcoin-httpd`` service listens for HTTP connections
+on a UNIX domain socket. To make the service publicly available, a reverse
+proxy such as nginx should be used. We strongly recommend to configure nginx
+to use TLS.
+
+The ``depolymerizer-bitcoin-bank`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+ # vim /etc/nginx/sites-available/depolymerizer-bitcoin
+ < ... customize configuration ... >
+ # ln -s /etc/nginx/sites-available/depolymerizer-bitcoin /etc/nginx/sites-enabled/depolymerizer-bitcoin
+ # systemctl reload nginx
+
+With this last step, we are finally ready to launch the
+main depolymerizer process.
+
+Launching the depolymerizer
+---------------------------
+
.. code-block:: console
$ sudo systemctl start depolymerizer-bitcoin.target
\ No newline at end of file
diff --git a/taler-magnet-bank-manual.rst b/taler-magnet-bank-manual.rst
@@ -352,7 +352,7 @@ enabled in nginx:
With this last step, we are finally ready to launch the
main adapter process.
-Launching an adapter
+Launching the adapter
---------------------
.. code-block:: console
