User Guide#

This section provides a high level overview for using ripple1d for production, including starting the ripple server and submitting jobs

Note

ripple1d is in active development and changes will be made frequently as production activities test the crurrent design and features.

Installation#

ripple1d is registered with PyPI and can be installed simply using python’s pip package installer. Assuming you have Python already installed and setup:

pip install ripple1d

Note that it is highly recommended to create a python virtual environment to install, test, and run ripple.

When successfully installed, a standalone executable will be available (stored in the path) allowing you to manage the Flask API and Huey consumer direcly by calling ripple1d in either a Command Prompt or PowerShell terminal Below are the steps to start the Ripple Manager, including the thread_count option for allocating the number of cpu’s to dedicate to ripple jobs..

Starting the server#

The utilities of ripple1d are accessed via an API, and the backend server must be started before any jobs can be processed.

Start the Ripple Services:

ripple1d start --thread_count 5

Help for the Ripple Services:

ripple1d -h

ripple1d start -h

By default, starting ripple1d will launch 2 terminal windows, one for the Flask API and the other for the Huey consumer. Logs for each of these services are stored in the same directory where ripple1d was started. For example, if you started ripple1d in the directory C:\Users\user\Desktop, the you will see 2 new files appear on the Desktop:

Server log: 2024-08-18T18-46-42.828592+00-00-ripple1d-flask.jsonld

Jobs log: 2024-08-18T18-46-42.376085+00-00-ripple1d-huey.jsonld`

Verify that ripple is running by checking the status here: http://localhost/ping

{"status" : "healthy"}

A healthy status indicates that ripple1d is running and waiting for jobs.

Index of Endpoints#

Jobs can be submitted using Postman collections, python clients, curl, or any other software that can communicate via HTTP REST protocol. The following endpoints reflect a typical workflow for ripple1d.

Example Endpoint Query#

import json
import requests

headers = {"Content-Type": "application/json"}
url = f"http://localhost/processes/gpkg_from_ras/execution"
payload = {
      "source_model_directory": 'path/to/ras_dir',
      "crs": 'EPSG:4326',
      "metadata": {
            "some_field": "relevant_data",
            "some_field2": "other data",
      },
   }
response = requests.post(url, data=json.dumps(payload), headers=headers)

Monitoring Logs#

Logs are provided in json-ld (linked data) format. The logs are written to file youing next line delimiting so the files can be read in and converted easily for evaluation.

An example of the huey (Jobs) log is shown here:

{"@type": "RippleLogs", "timestamp": "2024-08-18T18:46:42Z", "level": "INFO", "msg": "Huey consumer started with 4 thread, PID 5068 at 2024-08-18 18:46:42.444990"}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:46:42Z", "level": "INFO", "msg": "Scheduler runs every 1 second(s)."}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:46:42Z", "level": "INFO", "msg": "Periodic tasks are enabled."}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:46:42Z", "level": "INFO", "msg": "The following commands are available:\n+ ripple1d.api.tasks._process"}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:47:41Z", "level": "INFO", "msg": "Executing ripple1d.api.tasks._process: cc6cf9f2-ab0a-4a36-90a2-81e80157a907"}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:48:18Z", "level": "INFO", "msg": "Executing ripple1d.api.tasks._process: 19e04b34-ebf8-421e-850c-af8adff09728"}

An example of the flask (server) logs is shown here:

{"@type": "RippleLogs", "timestamp": "2024-08-18T18:49:07Z", "level": "INFO", "msg": "127.0.0.1 - - [18/Aug/2024 18:49:07] \"\u001b[35m\u001b[1mPOST /processes/extract_submodel/execution HTTP/1.1\u001b[0m\" 201 -"}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:49:13Z", "level": "INFO", "msg": "127.0.0.1 - - [18/Aug/2024 18:49:13] \"GET /jobs HTTP/1.1\" 200 -"}
{"@type": "RippleLogs", "timestamp": "2024-08-18T18:51:40Z", "level": "INFO", "msg": "127.0.0.1 - - [18/Aug/2024 18:51:40] \"GET /jobs HTTP/1.1\" 200 -"}

Troubleshooting#

For help troubleshooting, please add an issue on github at Dewberry/ripple1d#issues

On this page
Show Source