Skip to main content

One-shot Jobs

Service Lasso models one-shot jobs as setup.steps in service.json.

Use one-shot jobs for local work that must run after a service is installed/configured but should not be supervised as a daemon. Typical examples are schema initialization, sample data loading, certificate generation, dependency import, tool-cache preparation, and other repeatable setup work.

Do not use one-shot jobs for long-running servers, background workers, health-monitored daemons, or arbitrary application workflows that are unrelated to preparing the managed service.

When migrating donor manifests that used legacy execconfig.setup arrays and punctuation-prefixed setup lines, use Legacy Setup Migration before writing new setup.steps.

Contract​

Declare jobs under setup.steps:

{
  "setup": {
    "steps": {
      "init-schema": {
        "description": "Initialize the TypeDB schema.",
        "depend_on": ["typedb"],
        "execservice": "@java",
        "cwd": "${SERVICE_ROOT}/jobs",
        "commandline": {
          "win32": "-jar \"${SERVICE_ROOT}\\jobs\\typedb-init.jar\" --address ${TYPEDB_ADDRESS}",
          "default": "-jar \"${SERVICE_ROOT}/jobs/typedb-init.jar\" --address ${TYPEDB_ADDRESS}"
        },
        "timeoutSeconds": 120,
        "rerun": "manual"
      },
      "load-sample": {
        "description": "Load sample data into TypeDB.",
        "depend_on": ["typedb", "typedb:init-schema", "@python"],
        "execservice": "@python",
        "args": ["jobs/load-sample/basic_upload.py"],
        "timeoutSeconds": 300,
        "rerun": "manual"
      },
      "build-runtime-config": {
        "description": "Rebuild optimized runtime config when inputs change.",
        "executable": "${SERVICE_ARTIFACT_COMMAND}",
        "args": ["build"],
        "timeoutSeconds": 300,
        "rerun": "ifChanged",
        "fingerprint": [
          "${SERVICE_ARTIFACT_ROOT}",
          "${DATABASE_URL}",
          "${CONFIG_FILE_PATH}",
          "${SERVICE_ARTIFACT_TAG}"
        ]
      }
    }
  }
}

Common fields:

  • description: operator-facing summary for CLI/API/Admin surfaces.
  • depend_on: services or setup steps that must complete first. Setup step dependencies use <serviceId>:<stepId>.
  • execservice: optional provider service such as @node, @python, or @java.
  • commandline: platform map where win32, linux, or darwin override default.
  • executable and args: structured command form when a platform commandline is not needed.
  • cwd: optional working directory for the setup command. It supports normal Service Lasso variable selectors, resolves relative paths from the service root, must stay inside the service root, and must exist before the command runs.
  • env: setup-step environment additions.
  • timeoutSeconds: maximum runtime before the step is failed.
  • rerun: ifMissing, manual, always, or ifChanged.
  • creates: optional bounded file or directory paths expected after success. Service Lasso variables are resolved; rerun: ifMissing skips when every path exists and reruns when any path is missing or was deleted after a prior success. Guard results are stored as secret-free setup-state metadata.
  • fingerprint: optional bounded input templates for rerun: ifChanged. Service Lasso variables are resolved; the runtime stores a SHA-256 hash only, never the raw resolved values. The installed artifact release tag is included in the hash so an artifact-version change reruns the step.
  • outputs: optional bounded service-root-relative file paths created or replaced by the step. Declaring outputs lets transactional runtime startup restore pre-existing content or remove transaction-created files safely; undeclared command side effects are never guessed or deleted.

Runtime Behavior​

Service Lasso runs setup steps after install/config and before dependent startup work that needs the setup result.

Runtime behavior is intentionally different from daemon startup:

  • Direct setup omits execservice; the selected commandline is parsed as executable plus args, or executable plus args can be used.
  • Provider-backed setup uses the acquired provider command from @node, @python, @java, or another provider service.
  • Variables from service env, globalenv, provider globals, and runtime paths are resolved before execution.
  • When cwd is declared, Service Lasso resolves it before spawning the command, fails the setup step if it is missing or outside the service root, and records the resolved working directory in setup run history. When omitted, setup still runs from the service root.
  • Service dependencies are installed/configured first; non-provider service dependencies are started and health-checked before the step runs.
  • Setup step dependencies wait for the referenced setup step result before execution.
  • Stdout, stderr, exit code, timeout, start/end time, and status are persisted under .state/setup.json.
  • Baseline bootstrap runs non-manual setup steps and skips already successful ifMissing steps, including steps whose declared creates outputs are still present.
  • rerun: ifChanged skips a previously successful step when its fingerprint hash is unchanged, and reruns when declared inputs or the installed artifact release tag change.

CLI and API​

CLI:

service-lasso setup list
service-lasso setup run typedb
service-lasso setup run typedb init-schema --force
service-lasso setup run typedb --include-manual --json

API:

  • GET /api/setup
  • GET /api/services/:serviceId/setup
  • POST /api/services/:serviceId/setup/run/:stepId?

The API reports the same durable setup state that the CLI reads, so Service Admin and app hosts can surface setup history without inventing another contract.

TypeDB Use​

lasso-typedb owns the long-running TypeDB daemon. Schema initialization and sample data loading should be implemented as setup.steps in that service repo, not as separate fake daemon services.

Initialize a TypeDB app deliberately​

After your app has committed the released typedb manifest and started its declared dependencies, initialize the schema and then load sample data:

service-lasso setup run typedb init-schema
service-lasso setup run typedb load-sample

These steps are manual: a normal startup does not create a database, apply a schema, or load sample data. Use --force only when you intend to rerun one of those operations. Inspect the setup result and logs before retrying; Service Lasso records setup status, exit code, and history in .state/setup.json.

Tracked follow-up work: