|
| 1 | +# Configuration reference |
| 2 | + |
| 3 | +English | [Português](../pt-br/configuration.md) |
| 4 | + |
| 5 | +Options are set in code, in the callback of each `Add...` method, or bound from configuration. The ready-made hosts bind |
| 6 | +these sections, and you can do the same in your application: |
| 7 | + |
| 8 | +```csharp |
| 9 | +var configuration = builder.Configuration; |
| 10 | +builder.Services |
| 11 | + .AddPythonScriptRunner(o => configuration.GetSection("PythonScriptRunner").Bind(o)) |
| 12 | + .AddEntityFrameworkCore(o => |
| 13 | + { |
| 14 | + o.UseNpgsql(configuration.GetConnectionString("psr")!); |
| 15 | + configuration.GetSection("PythonScriptRunner:EntityFrameworkCore").Bind(o); |
| 16 | + }) |
| 17 | + .AddRabbitMq(o => |
| 18 | + { |
| 19 | + o.ConnectionString = configuration.GetConnectionString("rabbitmq"); |
| 20 | + configuration.GetSection("PythonScriptRunner:RabbitMQ").Bind(o); |
| 21 | + }) |
| 22 | + .AddWorker(o => configuration.GetSection("PythonScriptRunner:Worker").Bind(o)); |
| 23 | +``` |
| 24 | + |
| 25 | +In environment variables, sections are separated by `__`: `PythonScriptRunner__Worker__MaxConcurrency=8`. Time values use |
| 26 | +the `hh:mm:ss` format (`00:10:00`). |
| 27 | + |
| 28 | +## Runner (`PythonScriptRunner`) |
| 29 | + |
| 30 | +| Option | Default | Description | |
| 31 | +|--------|---------|-------------| |
| 32 | +| `WorkRoot` | `%TEMP%/psr` | Folder for the work and result folders of the attempts. | |
| 33 | +| `EnvironmentCacheRoot` | `%LOCALAPPDATA%/psr` | Folder where Python environments and lock files are cached. | |
| 34 | +| `UvPath` | `uv` | Path or name of the `uv` executable (searched in the PATH). | |
| 35 | +| `DefaultPythonVersion` | `3.12` | Python version of stages that do not declare one. | |
| 36 | +| `DefaultTimeout` | 5 minutes | Timeout of stages that do not declare one. | |
| 37 | +| `DefaultMemoryLimitMb` | `1024` | Memory limit of stages that do not declare one. | |
| 38 | +| `MaxFileBytes` | 50 MB | Maximum size of one file. | |
| 39 | +| `MaxRunFilesBytes` | 200 MB | Maximum size of all files of one run. | |
| 40 | +| `MaxLogBytes` | 1 MB | Bytes of stdout and stderr kept per attempt (the tail). | |
| 41 | +| `MaxConcurrentProcesses` | processor count | Python processes running at the same time in this process. | |
| 42 | +| `ThreadsPerProcess` | not set | Threads of the numeric libraries in each process. When not set: 1 on Linux when the memory limit falls back to `RLIMIT_AS`, no limit otherwise. See [Memory limits](hosting.md#memory-limits). | |
| 43 | +| `PackageIndexUrl` | PyPI | Package index (pip `--index-url`). | |
| 44 | +| `ExtraIndexUrls` | none | Extra package indexes (pip `--extra-index-url`). | |
| 45 | +| `PsrunnerRequirement` | `psrunner==0.1.0` | The SDK installed in every environment: a pip requirement or the path of a local wheel. | |
| 46 | +| `OrphanRetention` | 24 hours | Age after which leftover work folders are deleted. | |
| 47 | + |
| 48 | +Secrets are read from `PythonScriptRunner:Secrets:<NAME>`. |
| 49 | + |
| 50 | +## Persistence (`PythonScriptRunner:EntityFrameworkCore`) |
| 51 | + |
| 52 | +| Option | Default | Description | |
| 53 | +|--------|---------|-------------| |
| 54 | +| `Retention:Artifacts` | 7 days | How long file contents are kept. | |
| 55 | +| `Retention:Runs` | 90 days | How long runs, steps, attempts, logs and file metadata are kept. | |
| 56 | +| `Retention:Audit` | 365 days | How long audit events are kept. | |
| 57 | +| `Maintenance:Enabled` | `true` | Runs the maintenance job (partitions, retention, cleanups) in this process. | |
| 58 | +| `Maintenance:Interval` | 1 hour | How often the maintenance job runs. | |
| 59 | +| `Maintenance:BatchSize` | `1000` | Rows handled per batch by the maintenance job. | |
| 60 | +| `IdempotencyWindow` | 24 hours | How long an idempotency key returns the same run. | |
| 61 | +| `LatestVersionCacheDuration` | 30 seconds | How long "latest published version" lookups are cached in this process. | |
| 62 | +| `UseDatabaseClock` | `true` | Uses the PostgreSQL clock for leases, retry delays, schedules and the outbox, so hosts with skewed clocks agree. | |
| 63 | + |
| 64 | +The connection is set in code with `o.UseNpgsql(connectionString)`. |
| 65 | + |
| 66 | +## RabbitMQ (`PythonScriptRunner:RabbitMQ`) |
| 67 | + |
| 68 | +| Option | Default | Description | |
| 69 | +|--------|---------|-------------| |
| 70 | +| `ConnectionString` | none | AMQP URI: `amqp://user:password@host:5672/vhost`, or `amqps://` for TLS. | |
| 71 | +| `DeclareTopology` | `true` | Declares exchanges and queues at startup. With `false`, startup only checks that they exist (for brokers managed by an operator). | |
| 72 | +| `RunOutboxRelay` | `true` | Publishes the outbox from this process. Several instances can run it. | |
| 73 | +| `EnablePublicCommands` | `true` | Consumes the public `StartPipelineRun` command. | |
| 74 | +| `InstanceId` | machine name and process id | Names the per-instance queues of this process. | |
| 75 | +| `RelayInterval` | 250 ms | How often the relay looks for messages when the outbox is idle. | |
| 76 | +| `RelayBatchSize` | `100` | Messages published per relay batch. | |
| 77 | +| `DeliveryLimit` | `5` | Delivery attempts of a command before it goes to `psr.dead-letter`. | |
| 78 | +| `StartupConnectTimeout` | 10 seconds | How long startup waits for the broker before continuing in the background. | |
| 79 | + |
| 80 | +## Worker (`PythonScriptRunner:Worker`) |
| 81 | + |
| 82 | +| Option | Default | Description | |
| 83 | +|--------|---------|-------------| |
| 84 | +| `WorkerId` | the RabbitMQ instance id | Identifier recorded on the attempts this worker runs. | |
| 85 | +| `MaxConcurrency` | processor count | Steps executed at the same time by this worker. | |
| 86 | +| `LeaseDuration` | 60 seconds | Lease of a running attempt; another worker recovers it when not renewed. | |
| 87 | +| `LeaseRenewInterval` | 15 seconds | How often the lease of a running attempt is renewed. | |
| 88 | +| `ReaperInterval` | 15 seconds | How often expired leases are looked for. | |
| 89 | +| `MaxLeaseRecoveries` | `3` | Recoveries of one step after lost workers before it fails with `WorkerLost`. | |
| 90 | +| `ShutdownGracePeriod` | 5 minutes | How long running steps may finish when the host stops. The platform must allow at least this long. | |
| 91 | +| `WorkFolderCleanupInterval` | 1 hour | How often leftover work folders are removed. | |
| 92 | +| `Scheduler:Enabled` | `true` | Fires schedules from this worker. Several workers never fire the same occurrence. | |
| 93 | +| `Scheduler:PollInterval` | 5 seconds | How often due schedules are looked for (the firing precision). | |
| 94 | +| `Scheduler:BatchSize` | `50` | Schedules fired per transaction. | |
| 95 | + |
| 96 | +## Dashboard fixed login (`PythonScriptRunner:Dashboard:Login`) |
| 97 | + |
| 98 | +| Option | Default | Description | |
| 99 | +|--------|---------|-------------| |
| 100 | +| `Users` | none | List of `{ Name, Role, PasswordHash }`. | |
| 101 | +| `SlidingExpiration` | 8 hours | Session lifetime, renewed while the user is active. | |
| 102 | +| `AbsoluteExpiration` | 24 hours | Maximum session lifetime. | |
| 103 | +| `MaxFailedAttempts` | `5` | Failed logins in a row before the user is locked. | |
| 104 | +| `LockoutDuration` | 15 minutes | How long a locked user waits. | |
| 105 | +| `MaxAttemptsPerMinutePerIp` | `10` | Login attempts allowed per IP per minute. | |
| 106 | + |
| 107 | +The same options exist in code on `UseFixedLogin(l => ...)`, which also has `PersistKeysInDatabase` (default `true`): it |
| 108 | +keeps the cookie keys in PostgreSQL, so sessions work on every instance and survive restarts. |
0 commit comments