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:

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:

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 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 HTTP Endpoints.

3. Configure the service

The service configuration can be modified at runtime via the administration endpoints. See HTTP 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 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).