Custom Tasks

Create custom scheduled tasks for operations beyond built-in health checks and backups.

Custom Task Types

Create Container Update Task

Automatically update project container images:

Via API

curl -X POST https://supascale.example.com/api/v1/tasks \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Container Updates",
    "enabled": true,
    "type": "container-update",
    "projectId": "production",
    "cronExpression": "0 4 * * 0",
    "timezone": "UTC",
    "containerUpdateConfig": {
      "pullImages": true,
      "restartAfterUpdate": true
    }
  }'

Configuration Options

Create Custom Script Task

Run custom maintenance scripts:

curl -X POST https://supascale.example.com/api/v1/tasks \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Vacuum",
    "enabled": true,
    "type": "custom",
    "projectId": "production",
    "cronExpression": "0 5 * * 0",
    "timezone": "UTC",
    "customConfig": {
      "command": "docker exec production-db psql -U postgres -c \"VACUUM ANALYZE;\""
    }
  }'

Common Custom Tasks

Database Maintenance

{
  "name": "Weekly VACUUM",
  "type": "custom",
  "cronExpression": "0 5 * * 0",
  "customConfig": {
    "command": "docker exec ${PROJECT_ID}-db psql -U postgres -c 'VACUUM ANALYZE;'"
  }
}

Log Rotation

{
  "name": "Rotate Logs",
  "type": "custom",
  "cronExpression": "0 0 * * *",
  "customConfig": {
    "command": "find /var/log/supascale -name '*.log' -mtime +7 -delete"
  }
}

Cleanup Temp Files

{
  "name": "Cleanup Temp",
  "type": "custom",
  "cronExpression": "0 3 * * *",
  "customConfig": {
    "command": "find /tmp -name 'supascale-*' -mtime +1 -delete"
  }
}

Disk Space Check

{
  "name": "Disk Space Alert",
  "type": "custom",
  "cronExpression": "0 */6 * * *",
  "customConfig": {
    "command": "df -h / | awk 'NR==2 {if ($5+0 > 80) exit 1}'"
  }
}

Task Execution Environment

Custom commands run with:

• Working directory: Supascale installation directory
• User: Supascale process user
• Environment: Access to environment variables
• Timeout: Default 5 minutes

Available Variables

Viewing Task Results

Via API

curl https://supascale.example.com/api/v1/tasks/task-123 \
  -H "X-API-Key: your-api-key"

Response:

{
  "id": "task-123",
  "name": "Database Vacuum",
  "lastRun": "2026-01-19T05:00:00Z",
  "lastStatus": "success",
  "history": [
    {
      "executedAt": "2026-01-19T05:00:00Z",
      "status": "success",
      "duration": 15000,
      "output": "VACUUM\n"
    }
  ]
}

Run Task Immediately

Test custom task:

curl -X POST https://supascale.example.com/api/v1/tasks/task-123/run \
  -H "X-API-Key: your-api-key"

Response:

{
  "success": true,
  "execution": {
    "status": "success",
    "duration": 15000,
    "output": "VACUUM\n"
  }
}

Error Handling

Task Failure

Tasks fail if:

• Command returns non-zero exit code
• Execution times out
• Command not found

View Errors

Check task history for failure details:

{
  "history": [
    {
      "executedAt": "2026-01-19T05:00:00Z",
      "status": "failed",
      "error": "Command timed out after 300000ms"
    }
  ]
}

Best Practices

Security

1. Avoid sensitive data in commands
2. Use environment variables for secrets
3. Limit permissions of Supascale user
4. Audit task commands regularly

Reliability

1. Test commands manually first
2. Set appropriate timeouts
3. Handle errors gracefully
4. Log important output

Maintenance

1. Document tasks and their purpose
2. Review periodically for relevance
3. Monitor execution history
4. Clean up unused tasks

Troubleshooting

Command Not Found

1. Use absolute paths
2. Verify command exists
3. Check PATH in environment

Permission Denied

1. Check file/directory permissions
2. Verify Supascale user has access
3. Consider using sudo (if configured)

Timeout

1. Increase timeout setting
2. Optimize command performance
3. Split into smaller tasks
4. Run during low-activity periods