DRAFT: Taskfile.yaml to facilitate orchestration of Cosmos

[haisamido]

Closes #2840

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[ryanmelt]

One of my requirements for COSMOS is that it only requires Docker/Docker Compose. This appears like it would add another dependency on the host system. Is that accurate? Also what is the advantage over the existing openc3.sh/openc3.bat?

[haisamido]

One of my requirements for COSMOS is that it only requires Docker/Docker Compose. This appears like it would add another dependency on the host system. Is that accurate? Also what is the advantage over the existing openc3.sh/openc3.bat?

Very important question!

Why a Taskfile for OpenC3 COSMOS

openc3.sh is a 723-line bash script that serves as the single entry point for building, running, testing, and managing COSMOS. It works, but:

• Adding a command requires updating a case branch, the usage() help function, and a --help handler — three places kept in sync manually.
• Contributors must know which directory to cd into for each toolchain (openc3/ for Ruby, openc3/python/ for Python, openc3-cosmos-init/plugins/ for frontend).
• Environment loading (set -a; . .env; set +a) is repeated across four separate branches.
• Portability workarounds (docker vs podman, docker compose vs docker-compose, rootful vs rootless) add 40+ lines of detection logic.

What the Taskfile Provides

Discoverability — task --list shows every available command. No hand-maintained help text to keep in sync.

task
task: Available tasks for this project:
* api-cmd-tlm-test:              Run cmd-tlm-api RSpec tests
* api-script-runner-test:        Run script-runner-api RSpec tests
* build:                         Build all COSMOS Docker containers from source
* build-image:                   Build a specific Docker image
* build-ubi:                     Build COSMOS UBI containers
* cleanup:                       Remove all Docker volumes and data (DESTRUCTIVE!)
* cleanup-force:                 Remove all Docker volumes without confirmation
* cleanup-local:                 Remove Docker volumes and local plugin files
* cli:                           Run COSMOS CLI commands in a container
* cli-help:                      Show COSMOS CLI help
* cli-load:                      Load a plugin
* cli-validate:                  Validate a plugin
* cliroot:                       Run COSMOS CLI commands as root user
* default:                       Show available tasks
* frontend-build:                Build frontend shared packages
* frontend-install:              Install frontend dependencies
* frontend-lint:                 Run ESLint on frontend code
* hooks-install:                 Install git hooks
* logs:                          Follow logs from all containers
* ps:                            Show status of COSMOS containers
* python-coverage:               Run Python tests with coverage
* python-install:                Install Python dependencies
* python-lint:                   Run Python linter (ruff)
* python-test:                   Run Python tests
* ruby-build:                    Compile Ruby C extensions
* ruby-install:                  Install Ruby dependencies
* ruby-test:                     Run Ruby RSpec tests
* run:                           Start COSMOS containers in detached mode
* run-ubi:                       Run COSMOS with UBI containers
* setup:                         Run initial setup (download certificates, etc.)
* start:                         Build and run COSMOS (development) or just run (runtime)
* start-ubi:                     Build and run COSMOS with UBI images
* stop:                          Stop all COSMOS containers gracefully
* test-hash:                     Run comprehensive tests with coverage
* test-playwright:               Run Playwright end-to-end tests
* test-playwright-build:         Build the plugin for Playwright tests
* test-playwright-install:       Install Playwright and dependencies
* test-playwright-run:           Run Playwright tests
* test-rspec:                    Run RSpec tests against Ruby code
* util-clean:                    Remove node_modules, coverage, etc.
* util-encode:                   Encode a string to base64
* util-hash:                     Hash a string using SHA-256
* util-load:                     Load Docker images from tar files
* util-push:                     Push images to Docker repository
* util-save:                     Save Docker images to tar files
* util-tag:                      Tag images from one repo to another
* xtce-export:                   Convert COSMOS plugin to XTCE format
* xtce-import:                   Convert XTCE file to COSMOS configuration
* generate:plugin:               Generate a new plugin
* generate:target:               Generate a new target

Working directory handling — Each task declares its dir:. task ruby-test runs from openc3/, task python-test from openc3/python/, task frontend-build from openc3-cosmos-init/plugins/. Contributors don't need to know this.

Co-located documentation — task --summary <name> shows what a task does, its usage, and examples — all defined next to the commands themselves.

Declarative environment — dotenv: and vars: replace scattered set -a blocks. Defaults are explicit:

vars:
  CONTAINER_BIN: '{{.CONTAINER_BIN | default "docker"}}'
  PORT: '{{.PORT | default "2900"}}'

Safety — Destructive operations use a built-in prompt: directive instead of hand-rolled select yn menus.

Composition — start calls build then run via task: references, without re-executing the entire script and re-detecting docker/podman each time.

Automation Possibilities

• CI/CD — Each task is a self-contained step with its own dir:, dotenv:, and preconditions. Pipelines call task ruby-test instead of guessing openc3.sh arguments.
• Parallel execution — Independent tasks (Ruby tests, Python tests, frontend lint) can run concurrently via deps:.
• Watch mode — watch: true enables re-run-on-save without adding external file-watching tools.
• Composable files — includes: splits the Taskfile by domain (docker.yaml, ruby.yaml, python.yaml) as it grows.
• Stable interface — External tools invoke task <name> as a contract, without parsing shell script internals.

Cost

One static binary (task), installable via brew, go install, or direct download. For a project that already requires Docker, Ruby, Python, Node.js, and pnpm, this is negligible.

[haisamido]

Another example:

task --summary run
task: run

Start all OpenC3 COSMOS containers in detached mode.

Containers will run in the background. Access COSMOS at http://localhost:2900

Common services:
  - openc3-operator - Main orchestration service
  - openc3-cosmos-cmd-tlm-api - Command/Telemetry API
  - openc3-cosmos-script-runner-api - Script execution service
  - openc3-redis - Redis database
  - openc3-buckets - Object storage

vars:
  CONTAINER_BIN: "docker"
  ENV_FILE: ".env"
  COMPOSE_FILE: "compose.yaml"
  COMPOSE_BUILD_FILE: "compose-build.yaml"
  PORT: "2900"
  YELLOW_BOLD: "\033[1;33m"
  CYAN_BOLD: "\033[1;36m"
  RESET: "\033[0m"

env:
  OPENC3_DEMO: "1"
  OPENC3_DEPENDENCY_REGISTRY: "docker.io"
  OPENC3_REGISTRY: "docker.io"
  OPENC3_LOCAL_MODE: "1"
  OPENC3_REDIS_EPHEMERAL_HOSTNAME: "openc3-redis-ephemeral"
  OPENC3_REDIS_HOSTNAME: "openc3-redis"
  OPENC3_PLUGIN_DEFAULT_VOLUME: "/plugins/DEFAULT"
  OPENC3_SR_REDIS_USERNAME: "scriptrunner"
  OPENC3_GEMS_VOLUME: "/gems"
  OPENC3_UBI_TAG: "9.6"
  OPENC3_UBI_IMAGE: "ironbank/redhat/ubi/ubi9-minimal"
  MIGRATION_FILES_BEFORE_PAUSE: "10"
  OPENC3_TSDB_USERNAME: "openc3quest"
  SECRET_KEY_BASE: "bdb4300d46c9d4f116ce3dbbd54cac6b20802d8be1c2333cf5f6f90b1627799ac5d043e8460744077bc0bd6aacdd5c4bf53f499a68303c6752e7f327b874b96a"
  OPENC3_ENTERPRISE_REGISTRY: "ghcr.io"
  OPENC3_BUCKET_URL: "http://openc3-buckets:9000"
  OPENC3_LOGS_BUCKET: "logs"
  OPENC3_TOOLS_BUCKET: "tools"
  OPENC3_UBI_REGISTRY: "registry1.dso.mil"
  OPENC3_IMAGE_SUFFIX: ""
  OPENC3_TAG: "latest"
  ALPINE_BUILD: "3"
  OPENC3_BUCKET_USERNAME: "openc3bucket"
  OPENC3_SR_BUCKET_PASSWORD: "scriptrunnerbucketpassword"
  OPENC3_SERVICE_PASSWORD: "openc3service"
  PYPI_URL: "https://pypi.org"
  MIGRATION_PAUSE_SECONDS: "30"
  OPENC3_NAMESPACE: "openc3inc"
  OPENC3_REDIS_USERNAME: "openc3"
  OPENC3_REDIS_PORT: "6379"
  OPENC3_TSDB_QUERY_PORT: "8812"
  OPENC3_REDIS_PASSWORD: "openc3password"
  RUBYGEMS_URL: "https://rubygems.org"
  OPENC3_BUCKET_PASSWORD: "openc3bucketpassword"
  ALPINE_VERSION: "3.22"
  MIGRATION_SLEEP_SECONDS: "0.5"
  OPENC3_REDIS_EPHEMERAL_PORT: "6380"
  OPENC3_TSDB_HOSTNAME: "openc3-tsdb"
  NPM_URL: "https://registry.npmjs.org"
  OPENC3_CONFIG_BUCKET: "config"
  OPENC3_SR_REDIS_PASSWORD: "scriptrunnerpassword"
  OPENC3_SR_BUCKET_USERNAME: "scriptrunnerbucket"
  OPENC3_CLOUD: "local"
  OPENC3_AWS_ARN_PREFIX: "arn:aws"
  OPENC3_TSDB_INGEST_PORT: "9000"
  OPENC3_TSDB_PASSWORD: "openc3questpassword"
  MAVEN_URL: "https://repo.maven.apache.org/maven2"
  OPENC3_ENTERPRISE_NAMESPACE: "openc3"
  APK_URL: "https://dl-cdn.alpinelinux.org"
  MIGRATION_BATCH_SIZE: "1000"

commands:
 - Task: _check-root
 - docker compose -f compose.yaml up -d
 - echo ""
echo -e "\033[1;33mCOSMOS is started. Access the web interface at:\033[0m"
echo -e "  \033[1;36mhttp://localhost:2900\033[0m"
echo ""