quickstart

README

quickstart

quickstart 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 quickstart, 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/quickstart

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

Scoop (windows)

• scoop installation

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

Portable Executable

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

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

Basics

quickstart.yaml

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

To execute tasks defined in your configuration file:

quickstart up

output:

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

Using Docker

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

Command Line Interface (CLI)

quickstart provides a straightforward command-line interface.

Usage:

quickstart [command]

Available Commands:

Command	Descriptions
check	Confirm the correctness of the YAML content format.
completion	Generate the autocompletion script for the specified shell.
down	Kill previous tasks processes.
help	Help about any command.
up	Execute tasks according to the YAML configuration file.
version	Show version number and build details of quickstart.
init	Generate minimal quickstart.yaml file

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:

key	type	description
name	string, required	A unique identifier for the task.
base_dir	string	The working directory for the command. cmd.Dir will be set to this path. If not specified, the current working directory of quickstart will be used.
executable	string, required	The path to the executable command
args	[]string	A list of arguments to pass to the executable.
envs	[]string	A list of environment variables to set for the command
depends_on	[]string	A list of task names that this task depends on. This task will only start after all its dependencies have successfully passed their health checks.
healthcheck	object	Defines how quickstart determines if a task is healthy.
healthcheck.http	object	Configures an HTTP GET health check.
healthcheck.http.url	string, required	The URL to send the HTTP GET request to.
healthcheck.http.expect	object, optional	Defines expected responses.If not set, a 2xx HTTP status code indicates health.
healthcheck.http.expect.json	object	Expects a JSON response.
healthcheck.http.expect.json.jsonpath	string, required	A JSONPath expression to extract a value from the response.
healthcheck.http.expect.json.value	string, required	The expected value
healthcheck.command	object	Configures a command-based health check.
healthcheck.command.scripts	[]string, required	A list where the first element is the command, and subsequent elements are its arguments. The command is considered healthy if it exits with a zero status code.
healthcheck.frequency	object	Controls the timing of health checks.
healthcheck.frequency.interval	duration string	The time between consecutive health check attempts
healthcheck.frequency.timeout	duration string	The maximum time allowed for a single health check attempt
healthcheck.frequency.retries	int	The maximum number of consecutive failed health checks before the task is considered unhealthy.
healthcheck.frequency.delay	duration string	The initial delay before the first health check attempt is made after a task starts

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 quickstart 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
├─ quickstart.yaml
├─ (Optional) quickstart-portable(.exe)

Example of quickstart.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 quickstart portable executable or run quickstart up in your current directory's terminal.

Example 2: Portable Elasticsearch and Kibana Set

Here's an example of how you might configure quickstart 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/
├─ quickstart.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 quickstart.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 quickstart portable executable or run quickstart up in your current directory's terminal.

Implementations

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

Documentation

Overview

Copyright © 2025 Vulcan Shen vulcan.shen@tpisoftware.com