digiRocket

digiRocket(dgrkt)

dgrkt is a convenient command-line utility built with Go and Cobra. It's designed to orchestrate and execute a series of commands based on a declarative YAML configuration file, similar to how container orchestrators manage services. This tool simplifies the management of complex multi-command setups, making it ideal for local development environments, testing suites, or task automation.

With dgrkt, you define your tasks, their execution parameters, and their dependencies, allowing you to bring up and manage an entire set of related processes with a single command. It includes robust health check capabilities, ensuring that each task is healthy before dependent tasks are started.

Features

• Declarative Configuration: Define all your commands and their settings in a human-readable YAML file.
• Process Orchestration: Run multiple commands concurrently or sequentially based on defined dependencies.
• Comprehensive Health Checks: Ensure your tasks are healthy before proceeding.
  • HTTP Health Checks: Verify service availability via HTTP GET requests.
    • JSON Path Validation: Extract and validate specific values from JSON HTTP responses.
  • Command Health Checks: Use custom shell commands to determine task health.
• Dependency Management: Specify task dependencies to control the startup order.
• Flexible Execution: Set base_dir, executable, args, and envs for each task.

$\color{Red}\Huge{\textsf{Important Note!}}$

Because we have $\color{Red}\large{\textbf{NOT}}$ purchased Apple and Microsoft developer accounts, you'll currently need to manually bypass system security blocks when running the application.

Installation

Using Package Manager

Homebrew (macos/linux)

• homebrew installation

brew install --cask TPIsoftwareOSPO/tap/dgrkt

# macos (as "Important Note!" mention above)
xattr -dr com.apple.quarantine $(which dgrkt)

Scoop (windows)

• scoop installation

# add scoop tap
scoop bucket add TPIsoftwareOSPO https://github.com/TPIsoftwareOSPO/scoop-bucket.git
# install dgrkt
scoop install dgrkt

Portable Executable

Download the compressed file that matches your system from release. The filename prefix will be dgrkt-portable_.

To run the portable executable, it must be in the same directory with the dgrkt.yaml file.

Basics

dgrkt.yaml

tasks:
  - name: echo
    executable: echo
    args:
      - hello
      - world

To execute tasks defined in your configuration file:

dgrkt up

output:

dgrkt|Using config file: ...(ellipsis)/dgrkt.yaml
echo|hello world
echo|Completed

Using Docker

docker run --rm -v ./dgrkt.yaml:/app/dgrkt.yaml tpisoftwareopensource/dgrkt up

Command Line Interface (CLI)

dgrkt provides a straightforward command-line interface.

Usage:

dgrkt [command]

Available Commands:

Configuration File Reference

The tasks key at the root of your YAML file contains a list of individual task definitions. Each task can have the following properties:

Logging

The application's startup logs will be located in the logs/ directory.

Each log file will be named in the format {task:name}-{date}.log

Examples

Example 1: Java Application Portable Launch Package

Here's an example of how you might configure dgrkt to start .jar file using java command

Prerequisite

1. prepare your myapp.jar file.
2. (Optional) prepare portable jre. (e.g Azul Zulu)
3. create a new directory, put in your myapp.jar and jre directory. The file structure as below:

new-dir/
├─ jre/
    ├─ bin/
        ├─ java(.exe)
├─ myapp.jar
├─ dgrkt.yaml
├─ (Optional) dgrkt-portable(.exe)

Example of dgrkt.yaml

• With Portable Jre Java

  tasks:
    - name: myapp
      base_dir: .
      executable: jre/bin/java(.exe) # portable jre executable
      args:
        - -jar
        - myapp.jar
  

• Use System Jre Java

  tasks:
    - name: myapp
      base_dir: .
      executable: java # call system java command
      args:
        - -jar
        - myapp.jar
  

Double-click the dgrkt portable executable or run dgrkt up in your current directory's terminal.

Example 2: Portable Elasticsearch and Kibana Set

Here's an example of how you might configure dgrkt to start Elasticsearch and Kibana, with proper health checks and dependencies:

Prerequisite

1. download elasticsearch
2. download kibana
3. Unzip the downloaded files and place them in the same directory. The file structure as below:

files structure:

new-dir/
├─ elasticsearch/
├─ kibana/
├─ dgrkt.yaml
├─ kibana.yml

Example of kibana.yaml

csp.strict: false
server.ssl.enabled: false
telemetry:
  enabled: false
xpack:
  encryptedSavedObjects:
    encryptionKey: "01234567890123456789012345678901" # only for demo

Example of dgrkt.yaml

tasks:
  - name: elasticsearch
    base_dir: ./elasticsearch
    executable: bin/elasticsearch
    args:
      - -E
      - xpack.security.enabled=false
      - -E
      - xpack.security.http.ssl.enabled=false
      - -E
      - xpack.security.transport.ssl.enabled=false
      - -E
      - xpack.monitoring.collection.enabled=true
    healthcheck:
      frequency:
        interval: 5s
        timeout: 10s
        retries: 5
        delay: 5s
      http:
        url: http://localhost:9200
  - name: kibana
    base_dir: ./kibana
    executable: bin/kibana
    args:
      - -c
      - kibana.yml
    healthcheck:
      frequency:
        interval: 5s
        timeout: 10s
        retries: 5
        delay: 5s
      http:
        url: http://localhost:5601/api/status
        expect:
          json:
            value: available
            jsonpath: "$.status.overall.level"
    depends_on:
      - elasticsearch
  - name: curl1
    executable: curl
    args:
      - -v
      - http://localhost:9200
    depends_on:
      - elasticsearch
  - name: curl2
    executable: curl
    args:
      - -v
      - http://localhost:5601/api/status
    depends_on:
      - kibana

Double-click the dgrkt portable executable or run dgrkt up in your current directory's terminal.

Implementations

• how-to-make-digirunner-opensource-launch-standalone