# Jobs

A job runs a one-off command inside a project's deployed image, to completion. It reuses the environment's current live image - no separate build - and inherits that environment's variables, so a command like `python manage.py migrate` sees the same database and configuration as your running app. Run it on demand, or schedule it with a cron.

## Creating a job

From **Jobs -> New Job**, pick a project and environment (the image source), enter the command and a timeout, and create it. Then use **Run now**, or attach the job to a [cron](https://orkestr.eu/docs/features/crons) to run it on a schedule.

```bash
# database migration
python manage.py migrate

# one-off data backfill
node scripts/backfill.js --since 2024-01-01

# seed or maintenance
rails db:seed
```

## How a run works

Each run is a fresh, one-shot container, not a change to your running app:

- orkestr places a container on a node and pulls the environment's current live image.
- It runs your command to completion, with the environment's variables injected.
- It captures stdout and stderr and the exit code, then tears the container down.
- Exit code 0 is success; anything else is recorded as a failure.

The container carries the same hardening as app containers - capabilities dropped, no new privileges, resource caps - but has no HTTP endpoint and no domain. It occupies a node slot only while running.

## Run history

- Every run records status, exit code, duration, and full logs.
- Runs triggered by a cron are tagged so you can tell them from manual runs.
- The most recent runs are kept per job so history stays bounded.

## Common uses

- **Database migrations** after (or before) a deploy.
- **Backfills and data fixes** against production data, in the real environment.
- **Scheduled maintenance** - cleanups, report generation, cache warming - paired with a cron.
- **Ad-hoc operations** you'd otherwise SSH in to run.

## Job vs Function vs Project

- **Job** - run a command inside an existing app's image. Best for migrations and maintenance against real data.
- **[Function](https://orkestr.eu/docs/features/functions)** - a standalone HTTP handler with its own URL.
- **[Project](https://orkestr.eu/docs/features/projects)** - the long-running app itself.

## Plan limits

- Jobs are available on the Pro plan.
- CPU and memory are plan-driven, sized like functions for predictable placement.
- Timeouts are configurable per job, up to a per-run maximum.

> **Needs a live deployment**
>
> A job runs the environment's current live image, so deploy the project at least once before running a job against it. If there's no live deployment, the run fails with a clear message.

## FAQ

### Does a job affect my running app?

No. It runs in a separate one-shot container from the same image; your app container is untouched.

### Will two runs of the same job overlap?

Manual runs are independent. When driven by a cron, the cron's overlap policy controls whether a new run starts while one is still going.

### Where do I see the output?

On the job's run history - expand any run to see its logs and exit code.

### Can a job reach my database add-on?

Yes - it runs with the environment's variables and on the network it needs, so the same connection strings your app uses are available.