Task deployment commands

The CosmicAC deployment repository uses Task to deploy and operate the Docker Compose stack. You run each command from the deployment directory. task with no command lists every command.

Syntax

task <command> [VARIABLE=value ...] [-- <script-arguments>]

VARIABLE=value: a variable for this run. A value on the command line overrides the same variable in .env.
-- <script-arguments>: arguments for the underlying script. They take effect only after the -- separator.

Variables

Commands read the following variables from the command line or from .env. For every .env variable, see Deployment configuration.

Variable	Description
`TAG`	The release image tag. A value on the command line also overrides the per-service tags in `.env`, such as `APPNODE_TAG`, and CosmicAC doesn't save it to `.env`.
`SERVICES`	Space-separated Compose service names, such as `"cosmicac-app-node cosmicac-ui"`. Limits the command to those services.

Deploy

Command	Description	Variables
`task bootstrap`	Deploys the whole stack from scratch. Runs `config-init`, applies the `.env` configuration overrides, starts the services, and runs `wire`, `wire-monitor`, `autobase-connect`, `register-rack`, and `migrate-pricing`. Generates the service secrets, and copies the `apiKeySecret` of `cosmicac-app-node` to `cosmicac-proxy-inference`.	`TAG`
`task config-init`	Writes the configuration files of each service under `services/<service>/config/` from the examples in its image. Generates the `cosmicac-app-node` secrets and the proxy HRPC key pair.	None
`task pull`	Pulls the images at the resolved tag.	`TAG`, `SERVICES`
`task up`	Creates and starts the stack.	`TAG`, `SERVICES`

Lifecycle

Command	Description	Variables
`task start`	Starts the containers that `task stop` stopped.	`SERVICES`
`task stop`	Stops the containers without removing them.	`SERVICES`
`task restart`	Recreates the containers, even if they're unchanged.	`TAG`, `SERVICES`
`task down`	Stops and removes the containers and the network. Keeps the configuration and state directories.	None
`task update`	Upgrades to a new image tag. Pulls the images, adds new configuration files and keys, applies the `.env` configuration overrides, and recreates the services. Then runs `wire` and `wire-monitor` for the services in scope. Updating `cosmicac-app-node` also recreates `cosmicac-ui` and `caddy`.	`TAG`, `SERVICES`
`task recreate-ui`	Rebuilds the web interface assets and recreates Caddy.	None

Status and debugging

Command	Description	Variables
`task`	Lists the available commands.	None
`task ps`	Shows the container status. `task status` is an alias.	None
`task logs`	Follows the container logs.	`SERVICES`
`task config`	Renders the effective Docker Compose configuration.	None
`task config-diff`	Shows how the configuration of each service differs from the example in its image, with secrets redacted. Compares the live file plus its `.env` overrides, and writes nothing. Requires `jq` and `diff`.	`SERVICES`

Command	Description	Variables
`task login`	Logs in to GitHub Container Registry (GHCR). Uses `GITHUB_PAT` and `GITHUB_USER`, or prompts for them.	None
`task ensure-login`	Logs in to GHCR only if Docker has no stored credentials for it. You can't run it on its own. `task register-rack` runs it first.	None

Keys and wiring

Command	Description	Variables
`task wire`	Derives the runtime keys from the service status files, and updates the Docker Compose configuration and `.env`. Links the shared keys of the services, including the `apiKeySecret` of `cosmicac-proxy-inference`, and applies the `K8S_` configuration overrides.	None
`task wire-monitor`	Adds the RPC client key of `cosmicac-app-node` to the list of allowed keys of `cosmicac-wrk-monitor`, and writes the RPC public key of the monitor to `cosmicac-app-node`.	None
`task ork-key`	Prints the RPC public key of `cosmicac-wrk-ork`.	None
`task app-node-key`	Prints the Autobase bootstrap key of `cosmicac-app-node`.	None
`task autobase-connect`	Registers the Autobase writer key of every worker in `cosmicac-app-node`.	None
`task register-rack`	Registers the Kubernetes rack with `cosmicac-wrk-ork`, using `K8S_RACK_ID` and `K8S_RACK_LOCATION`.	None
`task migrate-pricing`	Applies `K8S_GPU_PRICE` to the GPU types on the registered racks.	None
`task seed-admin`	Creates or updates an administrator account from the `BOOTSTRAP_ADMIN_*` variables. No other command runs it.	None

Five services keep their configuration under DATA_ROOT, which defaults to services/. The settings of each service are in services/<service>/config/common.json, with more files under config/facs/. cosmicac-ui serves a static site and has no configuration directory.

task config-init copies the *.example file for each configuration file from the image of each service. If a live file is missing, the command creates it from the example. If the live file exists, the command adds each key that the example has and the live file lacks, and leaves the existing keys unchanged.

Each apply command reads the .env variables that carry its prefix, and writes their values to the config/common.json and config/facs/*.json files of one service. A variable replaces the value at the path that it names. The command starts no containers.

Command	Service	`.env` prefix
`task apply-app-node-common-config`	`cosmicac-app-node`	`APPNODE_`
`task apply-proxy-inference-common-config`	`cosmicac-proxy-inference`	`PROXY_`
`task apply-wrk-ork-common-config`	`cosmicac-wrk-ork`	`WRKORK_`
`task apply-wrk-server-k8s-nvidia-common-config`	`cosmicac-wrk-server-k8s-nvidia`	`K8S_`
`task apply-wrk-monitor-common-config`	`cosmicac-wrk-monitor`	`MONITOR_`

For the override variable forms and how a file key resolves to a filename, see Config overrides. A variable that carries the prefix but matches none of those forms produces a warning, and the command applies nothing from it.

The apply commands accept the following script argument.

Argument	Description
`--dry-run`	Prints the files that the command would write, and writes nothing. `--show-config` is an alias.

task bootstrap and task update also run all five apply commands.

task wire rewrites the values that link the services to each other, including the RPC allowlist in the net.config.json file of each service. task bootstrap and task update run it after the apply commands, so it replaces any of those values that an apply command wrote. The .env variable stays, and the apply command writes the value again. K8S_ overrides are the exception, because task wire applies them after its own writes.

Backup

Command	Description	Variables
`task backup`	Copies the configuration and state directories of each service to `./backups/<timestamp>`.	None

Destructive commands

Neither command takes a backup first, and no command restores what they delete.

Command	Description	Asks first	Variables
`task clean-state`	Deletes the `status` and `store` directories of the worker services in `SERVICES`. They refill on the next `task up`. The command needs `SERVICES`, and deletes nothing without it.	Yes	`SERVICES`
`task clean`	Deletes the containers, the Docker Compose volumes, the generated data of every service under `DATA_ROOT`, and the locally built images.	No	None