shc job

Jobs in SHC execute commands at specific points during stack lifecycle operations or on-demand. The shc job commands let you list, run, and monitor jobs.

Overview

Jobs execute commands with full access to stack mounts and networking. They are used when operations need to interact with running services or access live data.

Job Contexts

Context	Description	Use Case
`service`	Execute in an existing running service	`CHECKPOINT` on running DB
`container`	Spin up ephemeral container with stack access	Migration scripts, data jobs
`http`	Make HTTP request to a service	Health checks, API calls

Jobs vs Converters

Aspect	Jobs	Converters
When runs	While stack is running	After snapshot, stack resumed
Network	Full stack network access	`network_mode: none` (isolated)
Mounts	Live volumes (read/write)	Snapshot (read-only) + output dir
Purpose	Interact with services	Transform data into backup format
Used by	Hooks, restore, integrations	Backups only

shc job ls

List jobs defined for a stack:

# List all jobs for a stack (positional stack name)
shc job myapp

# List jobs with details
shc job myapp --verbose

# Filter by hook type
shc job myapp --hook post_install

Output

$ shc job postgres

Jobs for postgres:

  Name              Context    Hook           Description
  ────────────────────────────────────────────────────────
  flush_checkpoint  service    pre_backup     Flush DB checkpoint
  create_database   service    integration    Create user database
  migrate           container  post_install   Run database migrations
  health_check      http       -              Check service health

shc job run

Run a job manually:

# Run a specific job
shc job run --stack myapp --job migrate

# Run with environment variables
shc job run --stack myapp --job migrate --env FORCE=true

# Run with timeout override
shc job run --stack myapp --job long_task --timeout 600

# Dry run (show what would execute)
shc job run --stack myapp --job migrate --dry-run

Output

$ shc job run --stack postgres --job flush_checkpoint

Running job: flush_checkpoint
  Context: service (postgres)
  Command: psql -c "CHECKPOINT"

Output:
CHECKPOINT

Job completed successfully (0.3s)

shc job status

Show status of running or recent jobs:

# Show recent job runs
shc job status --stack myapp

# Show specific job run
shc job status --stack myapp --job migrate

# Show detailed output
shc job status --stack myapp --job migrate --verbose

Output

$ shc job status --stack myapp

Recent jobs for myapp:

  Job       Started              Duration  Status
  ────────────────────────────────────────────────
  migrate   2025-01-15 12:30:00  2.3s      success
  migrate   2025-01-14 10:15:00  2.1s      success
  seed      2025-01-14 10:15:05  0.8s      success

Job Definition

Jobs are defined in *.job.yaml files within the app directory:

Service Context

Runs command inside an existing running container:

name: flush_checkpoint
context: service
service: postgres
command: psql -c "CHECKPOINT"
timeout: 60

Properties:

Property	Type	Description
`service`	string	Service name from compose (required)
`command`	string	Command to execute (required)
`user`	string	Run as specific user
`working_dir`	string	Working directory inside container

Container Context

Spins up an ephemeral container with stack network access:

name: migrate
context: container
image: myapp:latest
command: python manage.py migrate --noinput
volumes:
  - app_data:/app/data
environment:
  DATABASE_URL: "{{ integrations.postgres.socket.url }}"
timeout: 300

Properties:

Property	Type	Description
`image`	string	Docker image to use (required)
`command`	string	Command to execute (required)
`volumes`	list[string]	Volume mounts
`environment`	dict	Environment variables
`networks`	list[string]	Networks to attach (defaults to stack networks)
`user`	string	Run as specific user
`working_dir`	string	Working directory
`labels`	dict	Container labels

HTTP Context

Makes HTTP request to a service (no container created):

name: health_check
context: http
url: http://web:8080/health
method: GET
timeout: 30

name: notify_slack
context: http
url: "{{ vars.slack_webhook }}"
method: POST
headers:
  Content-Type: application/json
body:
  text: "Deployment of {{ stack }} complete"
retry: 3

Properties:

Property	Type	Default	Description
`url`	string	—	URL to request (required)
`method`	string	`GET`	HTTP method
`headers`	dict	—	Request headers
`body`	string/dict/list	—	Request body (JSON)
`retry`	integer	`0`	Retry attempts

Common Job Properties

All job contexts share these properties:

Property	Type	Default	Description
`name`	string	—	Job name (required)
`context`	string	—	`service`, `container`, `http`
`timeout`	integer	`300`	Timeout in seconds
`retry`	integer	`0`	Number of retries (with exponential backoff)

Lifecycle Hooks

Jobs are commonly referenced in lifecycle hooks:

hooks:
  post_install:
    - migrate
    - seed_data
  post_upgrade:
    - migrate
  pre_backup:
    - flush_checkpoint
  post_restore:
    - rebuild_indexes

Supported Hooks

Hook	When	Stack State	Use Case
`pre_install`	Before deployment	Not running	Validation
`post_install`	After containers healthy	Running	Migrations, initial setup
`pre_upgrade`	Before upgrade starts	Running	Pre-flight checks
`post_upgrade`	After upgrade completes	Running	Schema migrations
`pre_uninstall`	Before containers stop	Running	Graceful shutdown
`post_uninstall`	After containers removed	Not running	External cleanup
`pre_backup`	Before snapshot	Running (paused)	Quiesce writes
`post_backup`	After backup completes	Running	Resume operations
`pre_restore`	Before restore starts	Stopped	Validate backup
`post_restore`	After restore completes	Running	Rebuild indexes

Examples

Database Migration Job

name: migrate
context: service
service: web
command: python manage.py migrate --noinput

hooks:
  post_install:
    - migrate
  post_upgrade:
    - migrate

Pre-Backup Checkpoint

name: checkpoint
context: service
service: postgres
command: psql -c "CHECKPOINT"

hooks:
  pre_backup:
    - checkpoint

Notification Webhook

name: notify
context: http
url: "{{ vars.webhook_url }}"
method: POST
headers:
  Content-Type: application/json
body:
  event: "deployment_complete"
  stack: "{{ stack }}"
  environment: "{{ environment }}"
retry: 3

Data Seeding Job

name: seed
context: container
image: myapp:latest
command: python manage.py seed_data
volumes:
  - seed_data:/app/seeds:ro
environment:
  DATABASE_URL: "{{ integrations.postgres.socket.url }}"

Failure Behavior

If a job fails, SHC logs a warning and continues to the next job. Use retry for jobs with transient failures:

name: notify_webhook
context: http
url: "{{ vars.webhook_url }}"
retry: 3  # Retry up to 3 times with exponential backoff

For critical jobs that must succeed, the operation will fail if the job fails (e.g., pre_install hooks failing will abort installation).

shc job

Overview

Job Contexts

Jobs vs Converters

shc job ls

Output

shc job run

Output

shc job status

Output

Job Definition

Service Context

Container Context

HTTP Context

Common Job Properties

Lifecycle Hooks

Supported Hooks

Examples

Database Migration Job

Pre-Backup Checkpoint

Notification Webhook

Data Seeding Job

Failure Behavior

See Also