99 lines
3.5 KiB
ReStructuredText
99 lines
3.5 KiB
ReStructuredText
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).
|