# Run a command on a schedule

Add a scheduled job that runs a command in the app's image, with its whole environment, on one of its machines.

The job runs `/bin/sh -c "<command>"` in the app's image, with its whole environment (variables,
secrets and database bindings) on one of the app's machines. Replace app-id with the app's
id and job-id with the job's id.

## Prerequisites

- An image that contains `/bin/sh`. You can add a job before the app is deployed; it starts
  running once the app is deployed and its machine reports in.
- Permission for `deploy:CreateJob` on the app; `deploy:RunJob` to run it now, `deploy:DescribeJobs`
  to read its runs, `deploy:UpdateJob` to change, enable or disable it, `deploy:DeleteJob` to delete
  it.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Add the job

**Console**
1. Open the app's **Scheduled jobs** tab, then choose **Add job**.
2. For **Name**, enter `nightly-cleanup`.
3. For **Schedule**, enter `0 3 * * *`, or choose a preset. The schedule is stated in words with its
   next run times.
4. For **Command**, enter `node bin/cleanup.js`.
5. (Optional) For a compose app, for **Service**, choose the service whose image and environment the
   job runs with.
6. (Optional) For **Timeout (minutes)**, enter a value. The default is 60.
7. (Optional) Turn on **Start even if the previous run is still going** (`concurrency` `allow`).
8. Choose **Add job**. The job is listed with its next run and a switch that enables or disables
   it.

**CLI**
```sh
dcloud deploy jobs create app-id --name nightly-cleanup \
  --schedule '0 3 * * *' --command 'node bin/cleanup.js'
dcloud deploy jobs run app-id job-id
```

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/jobs
{ "name": "nightly-cleanup", "schedule": "0 3 * * *", "command": "node bin/cleanup.js" }
```

**Terraform**
```hcl
resource "dcloud_app_job" "nightly_cleanup" {
  app_id      = dcloud_app.web.id
  name        = "nightly-cleanup"
  schedule    = "0 3 * * *"
  command     = "node bin/cleanup.js"
  timeout_sec = 900
  concurrency = "skip"
}
```

A second job with the same name is refused with `409` "This app already has a job named
"nightly-cleanup"", and a job over the app's job quota with `409` "Quota exceeded: …".

**Run now** starts a job outside its schedule; the machine picks it up on its next poll. Before
any machine of the app has reported in, it is refused with `409` "The app has no machine that has
reported in yet. Deploy it first". Every run, with
its exit code and the last lines it printed, is listed under the job's runs (**View runs**), and is a
line in the app's activity.

## Job settings

| Field         | Rule                                                                                                                                             | Default               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| `name`        | lowercase letters, digits and hyphens, at most 63 characters; unique within the app                                                              | required              |
| `schedule`    | five-field cron in UTC: minute hour day-of-month month day-of-week; `*`, `a-b`, `*/n`, lists, `jan`–`dec`, `sun`–`sat`; or `@hourly` … `@yearly` | required              |
| `command`     | run with `/bin/sh -c`; the image needs a shell                                                                                                   | required              |
| `service`     | compose apps: whose image and environment the job runs with                                                                                      | the published service |
| `timeoutSec`  | 10–86400; the run is stopped and recorded as `timed_out` after this long                                                                         | 3600                  |
| `concurrency` | `skip`: a run due while the previous one is still going is recorded as `skipped`; `allow`: it starts anyway                                      | `skip`                |
| `enabled`     | a disabled job is not run on schedule; **Run now** still works                                                                                   | `true`                |

When day-of-month and day-of-week are both set, a day matching either fires, as in cron: `0 0 1 * 1`
runs on the 1st and on every Monday. Only UTC is supported.

## What a run sees

The image of the deployment that is live, and the environment as of that deployment: a variable
saved without redeploying reaches jobs when it reaches the app. For a compose app the job joins the
app's network, so `db` resolves as it does for the services. A run that is due while the machine is
down is not run late. Where the job runs is in
[What runs on your machines](what-runs-on-your-machines.md#scheduled-jobs).

## Run outcomes

Each run is `succeeded` (exit 0), `failed`, `timed_out`, `skipped`, or `lost` (the machine stopped
reporting on it, or no machine picked up a run-now within ten minutes). The last 100 lines of output
are kept with the run; the newest 500 runs of each job are kept. A failed, timed-out or lost run
emails the organization's owners and admins, at most once a day per job while it keeps failing; the
first failure after a success is emailed at once.

## Result

The job runs on its schedule on one of the app's machines. How many jobs an app may have is a quota;
see [Quotas](quotas.md).

## Related

- `deploy.jobs.create` · `dcloud deploy jobs create` · `dcloud_app_job`
