Add scheduled job support and OCI image pull job

[cmyers-mieweb]

Introduces ScheduledJob model, migrations, and seeder for cron-based job scheduling. Updates job-runner to process scheduled jobs and create pending jobs when schedule conditions are met. Adds support for defaultStorage on nodes, including migration, model, and form update. Implements oci-build-job utility to pull OCI container images to Proxmox nodes using API credentials and storage configuration.

[cmyers-mieweb]

---

Scheduled Jobs / OCI Image Pull Integration

Summary

• Add a new ScheduledJobs Sequelize model/migration
  Columns: id, schedule (STRING, cron expression), command (STRING), lastRunAt (DATETIME).
  Purpose: DB-driven cron-style scheduled tasks.

• Add defaultStorage column to Node model
  Allows OCI pulls to target the appropriate Proxmox storage.

• Seed a ScheduledJob
  Runs the OCI image pull job (create-a-container/utils/oci-build-job.js) for Debian 13 and Rocky 9.

• Extend the job-runner
  Evaluates ScheduledJobs before claiming pending jobs and creates new pending Job records when schedules fire.

• oci-build-job implemented
  Pulls OCI LXC images directly to Proxmox nodes (no Packer).

---

Why

• Enables recurring automated OCI LXC image pulls for configured Proxmox nodes.
• Centralizes scheduling in the database — configurable via API/UI.
• Keeps job-runner behavior unchanged by generating standard "pending" Job entries.

---

Files Changed (High-Level)

Migrations

• create-a-container/migrations/XXXXXX-create-scheduled-jobs.js
• create-a-container/migrations/XXXXXX-add-default-storage-to-nodes.js

Models

• create-a-container/models/scheduledjob.js
• node.js (added defaultStorage)

Seeders

• create-a-container/seeders/XXXXXX-seed-oci-scheduledjob.js

Job Runner

• job-runner.js (added processScheduledJobs, uses cron-parser)

Utils

• oci-build-job.js (invoked by ScheduledJob command)

UI

• form.ejs (added defaultStorage field)

package.json

• Added cron-parser dependency

---

Architecture Diagram (Mermaid)

graph LR
  A[ScheduledJobs] -->|"evaluated by"| B[Job Runner]
  B -->|"on match"| C[Jobs (pending)]
  C -->|"claimed by"| D[Runner Execution]
  D -->|"executes"| E[OCI Build Job Script]
  E -->|"uses"| F[Node Model (apiUrl, token, defaultStorage)]

Loading

---

Implementation Notes (Concise)

ScheduledJobs Table Columns

• id INTEGER PK AUTOINCREMENT
• schedule STRING (cron expression, e.g., "0 2 * * *")
• command TEXT/STRING
• lastRunAt DATETIME NULL
• createdAt / updatedAt

Job Runner: processScheduledJobs()

• Loads all ScheduledJobs
• Uses cron-parser to check if now matches
• Compares with lastRunAt to avoid duplicate runs
• Inserts a record in Jobs table with status "pending"
• Updates lastRunAt

Seeded Command

Typically runs:

node oci-build-job.js

Node Model

• Added defaultStorage (STRING, NULL)

---

Step-by-Step Setup (Windows Dev)

Install dependencies

cd c:\Users\cmyers\Documents\GitHub\opensource-server\create-a-container
npm install

Add cron-parser

npm install cron-parser --save

Run migrations

npm run db:migrate
# or:
npx sequelize db:migrate

Seed ScheduledJob

npm run db:seed:all
# or:
npx sequelize db:seed:all

Start job runner

node create-a-container/job-runner.js

Watch logs for scheduled job creation and OCI pull runs.

---

Testing Instructions

Quick Functional Test

1. Create a ScheduledJob with:

   * * * * *
   

2. Command:

   node oci-build-job.js
   

3. Start job-runner → expect new pending job every minute.

Manual run of OCI job

node create-a-container/utils/oci-build-job.js

Verify

• DB Jobs table inserts
• Per-node pull attempts logged
• Pull success/failure messages appear

---

Suggested Unit / Integration Tests

• Model tests
  Validate cron string correctness, lastRunAt updating logic.

• processScheduledJobs tests
  Mock DB + cron-parser, assert inserts.

• End-to-end
  Disposable DB → runner → assert job gets created.

• OCI pull smoke test
  Mock Proxmox API endpoint for /pull-image.

---

DB / Migration Verification Checklist

• ScheduledJobs table exists
• Nodes.defaultStorage column exists
• Seeded OCI ScheduledJob created

---

Admin UI

• Node create/edit form updated
• defaultStorage field now selectable/editable

---

Operational Notes

• Job-runner should run at least every 30–60 seconds.
• Cron expressions evaluated in server local time unless otherwise configured.
• lastRunAt is minute-granular to avoid duplicate runs.

---

Rollback

• Migration down scripts remove both new changes.
• Seeder undo removes the OCI ScheduledJob.

---

Security Notes

• Scheduled job commands run with full job-runner privileges.
• Restrict ScheduledJob management to trusted admins.
• Protect DB tokens & secrets.

---

Files to Review

• create-a-container/migrations/XXXX-create-scheduled-jobs.js
• create-a-container/models/scheduledjob.js
• create-a-container/migrations/XXXX-add-default-storage-to-nodes.js
• node.js
• create-a-container/seeders/XXXX-seed-oci-scheduledjob.js
• job-runner.js
• oci-build-job.js

---

Acceptance Criteria

• ScheduledJobs and defaultStorage exist in schema
• Job-runner enqueues Jobs based on schedule
• Seeded OCI job runs successfully
• Admin UI supports defaultStorage
• Automated tests cover scheduling + validation

---

Notes / TODOs

• Define timezone behavior (UTC vs local)
• Consider adding timezone field per schedule
• Consider adding enabled BOOLEAN
• Add audit logs for schedule → job creation

---

[runleveldev]

LGTM

[runleveldev]

This should default to /opt/opensource-server/create-a-container/templates/debian.Dockerfile