Quick Start Guide

ERDDAPUtil is designed to function as a sidecar container to ERDDAP, in that each ERDDAP server should have one instance of ERDDAPUtil running beside it. ERDDAPUtil will need access to the bigParentDirectory of ERDDAP, to the Tomcat configuration, and to data files.

Instructions

You will need to have Docker installed on your machine.

1. Create a directory for your project

2. Copy and paste the contents of the compose.yaml file below into compose.yaml

3. Create a subdirectory called erddaputil_config

4. Copy and paste the quick startup configuration below into .erddaputil.toml

5. Run docker compose up --detach

6. ERDDAP will be available on http://localhost:8080 and the metrics/management API on http://localhost:9173

Docker Compose

This simple example illustrates a minimal configuration for using ERDDAPUtil and ERDDAP in Docker via a compose file. This file would go in the same directory as a copy of the ERDDAPUtil repository (later to be released as a Docker Hub image to simplify this).

services:

    # ERDDAP
    erddap:
        image: axiom/docker-erddap:2.23-jdk17-openjdk
        volumes:
            - "ephemeral-data:/erddap_data"
            - "persistent-data:/persistent_data"
            - "erddap-content:/usr/local/tomcat/content/erddap"
        ports:
            - "8080:8080"
        environment:
            - "ERDDAP_bigParentDirectory=/erddap_data"
        networks:
            - erddap-network
        depends_on:
            - erddaputil_daemon

    # Management Daemon
    erddaputil_daemon:
        image: dfomeds/erddaputil:latest
        volumes:
            - "ephemeral-data:/erddap_data"
            - "persistent-data:/persistent_data"
            - "erddap-content:/erddap_content"
            - "./erddaputil_config:/erddap_util/config"
        networks:
            - erddap-network
        depends_on:
            - erddaputil_webapp

    # Web Application
    erddaputil_webapp:
        image: dfomeds/erddaputil:latest
        command: ["webserver"]
        volumes:
            - "ephemeral-data:/erddap_data"
            - "persistent-data:/persistent_data"
            - "erddap-content:/erddap_content"
            - "./erddaputil_config:/erddap_util/config"
        ports:
            - "9173:9173"
        networks:
            - erddap-network

    # AMPQ Listener (example only)
    # You will need either a pika-compatible AMPQ server (e.g. RabbitMQ) or Azure Service Bus to
    # use this and additional configuration. It is provided here for illustration purposes.
    #erddaputil_ampq:
    #    image: dfomeds/erddaputil:latest
    #    command: ["ampq"]
    #    volumes:
    #        - "ephemeral-data:/erddap_data"
    #        - "persistent-data:/persistent_data"
    #        - "erddap-content:/erddap_content"
    #        - "./erddaputil_config:/erddap_util/config"
    #    networks:
    #        - erddap-network
    #    depends_on:
    #        - erddaputil_daemon

networks:
    erddap-network:

volumes:
    ephemeral-data:
    persistent-data:
    erddap-content:

Quickstart Configuration

The configuration below should work out-of-the-box for the Docker compose file above. You will need to modify it to suit your use case. You can also provide configuration as environment variables if preferred by concatenating the section name with a dot and the key name, then replacing the dots with underscores (e.g. for “big_parent_directory” the environment variable is named ERDDAPUTIL_ERDDAP_BIG_PARENT_DIRECTORY. This does not work for configuration options that are lists, such as the peppers.

[erddaputil]
show_config = true
# Change these to something unique and secure in production
secret_key = "SECRET"
default_username = "admin"
default_password = "admin"
metrics_manager = "erddaputil.main.metrics.LocalPrometheusSendThread"

[erddaputil.erddap]
# Adjust to match as needed
big_parent_directory = "/erddap_data"
datasets_d = "/persistent_data/datasets.d"
datasets_xml = "/erddap_content/datasets.xml"  # Points to /usr/local/tomcat/content/erddap/datasets.xml on ERDDAP container
base_url = "http://erddap:8080/erddap"

[erddaputil.dataset_manager]
# Adjust if needed
backups = "/erddap_data/_dataset_backups"

[erddaputil.daemon]
# name of your daemon container here, if on the same network in Docker
host = "erddaputil_daemon"

[erddaputil.service]
host = "0.0.0.0"

[erddaputil.webapp]
# Adjust if needed
password_file = "/erddap_data/.erddaputil_webapp_passwords"

# Change this and keep it secret
peppers = ["SECRET2"]

[erddaputil.localprom]
# Name of your host here
host = "erddaputil_webapp"
port = 9173
# Use the default_username and default_password here unless you have made another account.
username = "admin"
password = "admin"

Pip Installation

ERDDAPUtil can also be installed as a Python module from pip:

python -m pip install erddaputil

Configuration for the Python module is in the file .erddaputil.toml in either the user’s home directory or the current working directory. Configuration can also be done via environment variables.

The Python module includes the CLI as well as the daemon, webapp, and AMPQ listener which can be called by the module:

# Daemon launching
python -m erddaputil daemon

# Web app (you need extras)
python -m pip install erddaputil[webapp]
python -m erddaputil webapp

# AMPQ listener (you need extras)
python -m pip install erddaputil[asb]
# OR
python -m pip install erddaputil[rabbitmq]
python -m erddaputil ampq

# CLI interface
python -m erddaputil cli [CLI ARGS AND OPTIONS]