Quick Start
===========

This guide walks you through starting the service with or without an initial
configuration.

The service is started with the command ``dump-things-service <storage root>``.
``<storage root>`` is a directory that will be used to store records for all
collections as well as the persisted configuration of the service.


1. Start the Service
---------------------

On an empty storage root
........................

If the directory ``<storage root>`` does not contain a persisted configuration,
for example, because it is empty, the service will start with an empty configuration.
In this case a *bootstrap* administrator token has to be provided via the option
``--admin-token-hash`` (otherwise it
would not be possible to modify the configuration are runtime because no
administrator token has been configured).

The following command starts the server on ``https://127.0.0.1:8000/`` with the
bootstrap administrator token ``mysecret``:

.. code-block:: bash

   dump-things-service /path/to/storage --host 127.0.0.1 --port 8000 --admin-token-hash 652c7dc687d98c9889304ed2e408c74b611e86a40caa51c4b43f1dd5913c5cd0


**Note**: an administrator token hash can be created via the command
``dump-things-hash-token <plain-text token>``.

**Note**: do not use the administrator token hash from the example above in your
installations, as it is publicly visible.


Alternatively to setting ``--admin-token-hash``, set the environment variable
``DTS_ADMIN_TOKEN`` to the plain-text bootstrap administrator token, before starting the service:

.. code-block:: bash

   export DTS_ADMIN_TOKEN=mysecret
   dump-things-service /path/to/storage


**Note**: do not use ``mysecret`` in your installations as it is publicly visible.
Use a strong secret instead.


On an empty storage root, initially configured via config-file
..............................................................

If the storage root does not contain a persisted configuration, the service will
look for a configuration file at ``<storage root>/.dumpthings.yaml``, unless
``--ignore-default-config-file`` or
``-c/--config <config file>`` is provided.

If ``--ignore-default-config`` is
provided, the server will ignore a configuration file at
``<storage root>/.dumpthings.yaml``.

If ``-c/--config <config file>`` is passed
on the command line, the server will
try to read the configuration from ``<config file>``. Once the configuration is
read, it will be persisted in the storage root.

See :doc:`configuration` for details on the configuration file format.

**Note**: on subsequent restarts, the service will ignore the configuration files
and use the persisted configuration.


2. Explore the API
------------------

Once the service is running, open your browser at
``http://127.0.0.1:8000/docs`` to explore the interactive Swagger UI for all
available endpoints.

For a full description of all endpoints see :doc:`endpoints`.


3. Configure the service
------------------------

The service configuration can be modified at runtime via the administration
endpoints. See :doc:`endpoints` for details.

An easy way to configure a running service is to use the command
``dump-things-upload-configuration`` to upload the content of a
configuration file via the administration endpoints (see :doc:`configuration`).

In combination with the command ``dump-things-download-config`` this command
can be used to "clone" an identically configured service instance (the cloned
service instance will have no records initially, but those can be cloned
from the original service instance as well).