﻿`[storage]` limits the disk space RunWisp uses for logs, across all tasks. It
works on top of the per-run [`log_max_size`](/configuration/tasks/#log_max_size).
Both keys are optional, but without them logs can fill the disk. On a server,
set both. [`runwisp reload`](/operations/reload/) applies a change.

Sizes use `b`, `kb`, `mb`, `gb`, `tb` (any case), with optional fractions
(`"1.5gb"`).

## Keys

```toml title="runwisp.toml"
[storage]
max_size       = "5gb"
min_free_space = "500mb"
```

### max_size

**type**: `size` **default**: `0` (no limit)

The total size of all log files (`.log` and their `.log.meta` files). The
database and other files in the data directory don't count.

```toml title="runwisp.toml"
[storage]
max_size = "5gb"
```

- A background job checks the total from time to time. When it is over the
  limit, it deletes the **oldest completed runs** (database rows and log files)
  until the total is under the limit again. The daemon logs:

    ```
    WARN  Log storage exceeds storage.max_size, purging oldest runs
    INFO  Purged runs to enforce storage.max_size  deleted=N
    ```

- The total can go a little over the limit between checks.
- A run that is still going is never deleted.
- Make it large enough to hold several full runs of your biggest task.
  Otherwise runs are deleted almost as fast as they are created.

### min_free_space

**type**: `size` **default**: `0` (no check)

The free space to keep on the partition that holds the data directory. It
never stops the daemon from starting.

```toml title="runwisp.toml"
[storage]
min_free_space = "500mb"
```

- **Before each run:** if free space is below the limit, the run doesn't start.
  It is recorded with exit code `-1` and the message
  `insufficient disk space: X free, minimum Y required`.
- **During each run:** about every 10 MB of output, free space is checked
  again. If it is below the limit, the log stops taking new lines, and a
  `log.disk_pressure` notification (severity `warn`) is sent once per run, with
  `free_bytes`, `min_free_bytes`, and `killed_task`. The task's
  [`log_on_full`](/configuration/tasks/#log_on_full) decides what happens to the
  process:
    - `drop_new` / `drop_old`: the process keeps running. The log gets the line
      `Log output stopped: disk space critically low`.
    - `kill`: the run is stopped with `end_reason = "log_overflow"`. The log gets
      the line `Process killed: disk space critically low …`.

## How the limits work together

| Limit                                                | Scope                  | What happens at the limit                                                       |
| ---------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
| [`log_max_size`](/configuration/tasks/#log_max_size) | one run's log          | [`log_on_full`](/configuration/tasks/#log_on_full): drop old, drop new, or kill |
| [`max_size`](#max_size)                              | all logs together      | oldest completed runs are deleted                                               |
| [`min_free_space`](#min_free_space)                  | free space on the disk | new runs don't start; running logs stop                                         |

## Suggested values

| Environment                  | [`max_size`](#max_size)        | [`min_free_space`](#min_free_space) |
| ---------------------------- | ------------------------------ | ----------------------------------- |
| Raspberry Pi (8 GB SD)       | `1gb`                          | `200mb`                             |
| Small VPS (40 GB SSD)        | `5gb`                          | `500mb`                             |
| Large VPS (200+ GB)          | `20gb`–`50gb`                  | `2gb`                               |
| Docker container (ephemeral) | match volume size, `1gb`–`5gb` | `500mb`                             |
