dump-things-service/docs/commands.rst

Command-Line Tools
==================

The package installs the following command-line tools.

Service Commands
----------------

dump-things-service
^^^^^^^^^^^^^^^^^^^

Start the Dump Things Service.

.. code-block:: text

   dump-things-service [OPTIONS] <storage-root>

**Arguments**

``<storage-root>``
   (Mandatory) Path to the directory used as anchor for all relative paths in
   the configuration.

**Options**

.. option:: --host <IP-address>

   IP address on which the service should accept connections.
   Default: ``0.0.0.0``.

.. option:: --port <port>

   Port on which the service should accept connections. Default: ``8000``.

.. option:: -c, --config <config-file>

   Path to a configuration file. If no persisted configuration is found in the
   data store, the service is initialized with the content of this file.
   Useful for migrating from service version <= 5 to version 6.

.. option:: --origins <origin>

   Add a CORS origin host. Repeat to add multiple CORS origin URLs.

.. option:: --root-path <path>

   Set the ASGI ``root_path`` for applications mounted below a given URL path.

.. option:: --log-level <LEVEL>

   Log level. Allowed values: ``ERROR``, ``WARNING``, ``INFO``, ``DEBUG``.
   Default: ``WARNING``.

.. option:: --admin-token-hash <sha256-hex>

   Set an administrator token hash (64-digit hexadecimal SHA-256 hash of the
   plain-text token). If not provided, a plain-text token is read from the
   environment variable ``DTS_ADMIN_TOKEN``, if it is set.

.. option:: --ignore-default-config-file

   If set, the service will not try to initialize itself from the default
   configuration file ``<storage-root>/.dumpthings.yaml``. Otherwise, if no
   persisted configuration is found in the data store (and ``-c/--config`` is
   not provided), the service will read its initial configuration from
   ``<storage-root>/.dumpthings.yaml`` if it exists.


**Example**

.. code-block:: bash

   dump-things-service /data/store --host 127.0.0.1 --port 8000


Configuration Tools
-------------------

dump-things-upload-config
^^^^^^^^^^^^^^^^^^^^^^^^^^

Read a configuration from a dump-things configuration-file and
instantiate its elements on a running server via the administration
endpoints. Objects that already exist on the server are left unchanged.

An admin token has to be provided in the environment variable
``DTS_ADMIN_TOKEN``.

.. code-block:: text

   dump-things-upload-config [OPTIONS] <config-file (json or YAML)>

**Options**

.. option:: --server <URL>

   Base URL of the running service (e.g. ``http://127.0.0.1:8000``).

.. option:: --format [{json,yaml}], -f [{json,yaml}]

    Specify the format of the input file. Possible values are `json` and `yaml`. If this option is given, the suffix of the configuration file is ignored.

.. option:: --send-to SEND_TO

    The base URL of the server API. If this option is provided, the configuration will be sent to the server API, otherwise it will just be written to stdout.

.. option:: --old-format

    If provided, assume that the configuration is in version 1 format and convert it to the new format internally (in version 1: tokens had no `hashed`-attribute and no `representation`-attribute, the token representation was the key of the token configuration, collections had no `schema`-attribute, and `sqlite`-backends had a `schema`-attribute).

.. option:: --store STORE

    If --old-format is provided, this option can be used to specify a store directory. The store directory will be used to load `RecordDir` configurations, if a collection defines are `RecordDir`-backend. (This option has no effect if no collection in the old configuration uses a `RecordDir`-backend.)


dump-things-download-config
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Read the current configuration from a running service and write it to a file.

An admin token has to be provided in the environment variable
``DTS_ADMIN_TOKEN``.

.. code-block:: text

   dump-things-download-config [OPTIONS] <server API URL>

**Options**

.. option:: --entities {admin_tokens,collections,tokens}, -e {admin_tokens,collections,tokens}

    Specify for which entities the configuration should be downloaded. Possible values are `admin_tokens`, `collections`, or `tokens` (repeat to download configuration for more than one entity). If this option is not provided, configurations for all entities will be downloaded.

.. option:: --format [{json,yaml}], -f [{json,yaml}]

    Specify the format of the output. Possible values are `json` and `yaml` (the default is `yaml`).


dump-things-hash-token
^^^^^^^^^^^^^^^^^^^^^^^^

Compute the SHA-256 hash of a plain-text token for use with ``--admin-token-hash`` or as ``representation``-value in a configuration object (file)

.. code-block:: bash

   dump-things-hash-token <plain-text-token>




Maintenance Tools
-----------------

dump-things-pid-check
^^^^^^^^^^^^^^^^^^^^^^

Check all PIDs in a store to verify they can be resolved (useful after
schema changes that affect prefix definitions).

.. code-block:: bash

   dump-things-pid-check <path-to-store>



Audit Tools
-----------

dump-things-gitaudit-report
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Report the audit information that was stored for all PIDs matching a pattern.
For every change to a record the tool will report: time stamp, user ID, diff, and the resulting record.

.. code-block:: bash

   dump-things-gitaudit-report <path-to-audit-dir> <pid-pattern>

``<pid-pattern>`` is a Python ``re``-module pattern that identifies PIDs of the record for
which audit information should be reported. Use ``'.*'`` to report changes for all PIDs.

Each log entry contains:

- Timestamp of the change.
- Curator ID.
- Diff of the change.
- The resulting record.


dump-things-gitaudit-rebuild-index
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Rebuild the index for a ``gitaudit`` backend. Normally not required in
regular operations; useful for maintenance.

.. code-block:: bash

   dump-things-gitaudit-rebuild-index <path-to-audit-dir>