# Running SIPI
SIPI can be run either as a command-line image converter or as an IIIF media server.
## Quick Start with Docker
```
docker run -p 1024:1024 daschswiss/sipi
```
## Running SIPI as a Command-line Image Converter
SIPI now uses verb-noun subcommands (`convert`, `query`, `compare`, `verify`, `server`, `health`) instead of the legacy `--convert` / `--query` / `--compare` / `--file` / `--outf` flags. A bare `sipi` invocation errors with a usage message — every operation needs an explicit subcommand.
Convert an image file to another format:
```
sipi convert input.tif output.jpg --format jpg
```
Query image file information:
```
sipi query input.tif
```
Compare two image files pixel-wise:
```
sipi compare file1.tif file2.jpg
```
## Running SIPI as a Server
```
sipi server --config config/sipi.config.lua
```
### Configuration file format (`.lua` or `.toml`)
`--config` accepts either a Lua file (`.lua`) or a TOML file (`.toml`), dispatched on the extension. The Lua file is parsed by the engine's Lua VM (SIPI's historical format); a TOML file is parsed directly by the server and needs no Lua VM in the config path. Route *scripts* are always Lua — TOML replaces the config *file*, not the scripting.
> **TOML config is experimental.** It is the first of the native (Rust/TOML) alternatives SIPI is introducing for everything Lua is used for today (see [ADR-0017](https://github.com/dasch-swiss/sipi/blob/main/docs/adr/0017-extensibility-lua-and-rust.md)). The schema may change without the usual compatibility guarantees until it is validated in production; the server logs a warning on startup when a `.toml` config is loaded. The Lua config path stays fully supported. Once the native alternatives stabilize, Lua will be marked deprecated.
A TOML config groups keys into sections that mirror the `server` flag groups, with idiomatic snake_case names:
```
[network]
port = 1024
[paths]
img_root = "/sipi/images" # required
script_dir = "/sipi/scripts"
init_script = "/sipi/config/sipi.init.lua"
[cache]
dir = "/sipi/cache"
size = "200M" # "0" disables the cache
[image]
jpeg_quality = 60
scaling_quality = { jpeg = "high", tiff = "high", png = "high", j2k = "high" }
[tls_auth]
jwt_secret = "…"
[[routes]]
method = "POST"
route = "/api/upload"
script = "upload.lua" # resolved against [paths].script_dir
```
Precedence is `config file < environment variable < command-line flag`, the same as for a Lua config: a CLI flag (or its `SIPI_*` env var) overrides the matching TOML key. `img_root` is required (an empty image root has nothing to resolve); routes with a relative `script` require `[paths].script_dir`. Unknown keys are rejected (a typo is a startup error, not a silently-ignored value), so transport knobs the Rust server does not own — TLS (`ssl_*`), `hostname`, `keep_alive`, thread count, and `logfile` — have no TOML key and are reported as unsupported.
The TOML key for each Lua config key:
| TOML key | Lua config key |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `[network] port` | `port` |
| `[paths] img_root` | `imgroot` |
| `[paths] script_dir` | `scriptdir` |
| `[paths] init_script` | `initscript` |
| `[paths] tmp_dir` | `tmpdir` |
| `[paths] max_temp_file_age` | `max_temp_file_age` |
| `[paths] doc_root` | `fileserver.docroot` |
| `[paths] www_route` | `fileserver.wwwroute` |
| `[paths] prefix_as_path` | `prefix_as_path` |
| `[paths] subdir_levels` | `subdir_levels` |
| `[paths] subdir_excludes` | `subdir_excludes` |
| `[cache] dir` | `cache_dir` |
| `[cache] size` | `cache_size` |
| `[cache] n_files` | `cache_nfiles` |
| `[limits] max_decode_memory` | `max_decode_memory` |
| `[limits] decode_memory_mode` | `decode_memory_mode` |
| `[limits] max_pixel_limit` | `max_pixel_limit` |
| `[limits] max_post_size` | `max_post_size` |
| `[limits] thumb_size` | `thumb_size` |
| `[image] jpeg_quality` | `jpeg_quality` |
| `[image] scaling_quality.{jpeg,tiff,png,j2k}` | `scaling_quality.{…}` (the `j2k` entry is accepted but currently has no effect — the engine reads that slot under a legacy key) |
| `[rate_limit] max_pixels` | `rate_limit_max_pixels` |
| `[rate_limit] window` | `rate_limit_window` |
| `[rate_limit] mode` | `rate_limit_mode` |
| `[rate_limit] pixel_threshold` | `rate_limit_pixel_threshold` |
| `[tls_auth] jwt_secret` | `jwt_secret` |
| `[tls_auth] admin_user` | `admin.user` |
| `[tls_auth] admin_password` | `admin.password` |
| `[knora] path` | `knora_path` |
| `[knora] port` | `knora_port` |
| `[logging] level` | `loglevel` |
| `[[routes]]` (`method`/`route`/`script`) | `routes` |
## Health Check
`sipi health` is a self-contained liveness probe. It performs an HTTP `GET` on the local [`/health`](https://sipi.io/operation/health-endpoint/index.md) endpoint and maps the result to a process exit code, following the Docker/Swarm healthcheck convention:
- **0** — the endpoint returned HTTP 200 (healthy).
- **1** — connection refused, timeout, or any non-200 response (unhealthy).
```
sipi health # probes http://127.0.0.1:1024/health
sipi health --port 80 # probe a server running on a different port
```
The host is always `127.0.0.1` and the path is always `/health`; only the port is configurable. A separate `sipi health` process cannot know whether the running server took its port from a config file, an env var, or `--serverport`, so the caller passes the port it configured (`--port`, default `1024`). The probe uses a short (~2 s) timeout so a wedged server reports unhealthy rather than hanging. Because it needs no `curl` in the image, it is the intended container/orchestrator liveness command (see [Health Endpoint](https://sipi.io/operation/health-endpoint/index.md)).
## Logging
SIPI uses two logging modes depending on how it is running:
- **CLI mode** (`convert`, `compare`, `query`): Plain text output. Errors go to **stderr**, informational messages go to **stdout**. This is the standard Unix convention for command-line tools. When `--json` is also set (see [Structured JSON output](#structured-json-output-cli)), every level is routed to **stderr** so `stdout` stays reserved for the single JSON document.
- **Server mode** (`sipi server --config`): JSON-formatted log lines go to **stdout**. This follows container best practices — Docker, Kubernetes, and log collectors (Grafana Loki, Fluentd) expect structured logs on stdout. Each line is a JSON object: `{"level": "INFO", "message": "..."}`.
### Log Levels
SIPI supports the following log levels (in order of increasing severity):
| Level | Description |
| --------- | ----------------------------------------------------------------------------------------- |
| `DEBUG` | Detailed diagnostic information. |
| `INFO` | Normal operational messages (routes added, server started, migrations). |
| `NOTICE` | Significant but normal events. |
| `WARNING` | Something unexpected but recoverable (e.g., failed XMP parse, incomplete metadata write). |
| `ERR` | Errors that affect a specific operation (e.g., image processing failure, ICC error). |
| `CRIT` | Critical errors. |
| `ALERT` | Conditions requiring immediate attention. |
| `EMERG` | System-wide emergencies. |
The log level controls which messages are emitted. Setting a level suppresses all messages below it. For example, `WARNING` shows only WARNING, ERR, CRIT, ALERT, and EMERG — suppressing DEBUG, INFO, and NOTICE.
The log level can be configured in three ways (in order of precedence):
1. **CLI option**: `--loglevel WARNING`
1. **Environment variable**: `SIPI_LOGLEVEL=WARNING`
1. **Lua config**: `loglevel = "WARNING"` (in the `sipi` block)
If none is specified, the default level is `INFO`.
## Command-line Options
### Image Conversion Options
These options are accepted by the `convert` subcommand (and where documented in the per-subcommand matrix, by `convert access-file` and `convert service-file`). Usage: `sipi convert