Appearance
Storage Providers Management
Overview
ODP supports multiple storage backends for file storage. Storage providers are configured via the admin API and stored in odp_extension_settings (with extension_key = 'system_storage_provider'). After any change, the StorageManager is re-initialized to pick up the new configuration.
Each provider has two lifecycle flags, stored in its JSON config: isActive (accepts new uploads) and isDefault (the storage used when an upload names none). See Active & Default Providers.
Supported Drivers
type | Description |
|---|---|
local | Local filesystem storage |
s3 | Amazon S3 or S3-compatible (e.g., MinIO, Backblaze B2). Optionally scan-gated (malware scan) |
A built-in local driver is always available, even when it is not configured — see Implicit local driver.
Sensitive Fields
The following storage fields are encrypted at rest using the server SECRET (STORAGE_SENSITIVE_FIELDS in service/api/src/utils/encryption.ts):
accessKeyIdsecretAccessKey
GET /system/storage-providers returns them masked as "********". On PATCH, sending the masked value keeps the stored secret.
Active & Default Providers
Flags
Field (in value) | Type | Legacy config (field missing) | Description |
|---|---|---|---|
isActive | boolean | active | false = closed to new uploads. Files already stored on it stay readable and deletable |
isDefault | boolean | not default | The provider used when an upload does not name a storage |
Rules (readProviderFlags in service/api/src/storage/manager.ts, assertValidFlags in service/api/src/routes/storage-providers.ts):
- Both flags are optional and, when sent, must be booleans — otherwise
400 INVALID_PAYLOAD("isActive" must be a boolean). - An inactive provider cannot be the default. Sending
isDefault: truetogether withisActive: falseis rejected with400 INVALID_PAYLOAD(An inactive storage provider cannot be the default). The check looks at thevaluesent in the request. - Only one default. When a provider is saved (create or update) with
isDefault: true, the server setsisDefault: falseon every other provider. - If several stored configs still carry
isDefault: true(e.g. edited directly in the DB), the first one byidwins and a warning is logged.
Default resolution
When an upload names no storage, StorageManager.getDefaultName() picks, in order:
- the provider flagged
isDefault, if it is registered and active; - otherwise
local, if active; - otherwise the first active driver.
A provider flagged isDefault whose driver failed to initialize (bad config, missing credentials) is not registered, so resolution falls through to local.
Inactive providers
An inactive provider is still registered, so files already on it keep working (serve, transform, delete). It is only closed to new uploads:
| Path | Behaviour when the named storage is inactive or unknown |
|---|---|
POST /files (multipart, storage field) and POST /files/import | 400 INVALID_PAYLOAD — Storage "<name>" is inactive and does not accept new uploads / Storage "<name>" does not exist |
POST /tus (storage in Upload-Metadata) | 400 with the same message as body |
GET /files/storage-locations | the provider is left out |
Replacing the content of an existing file (PATCH /files/:id with a file) writes to the storage the file already lives on.
Implicit local driver
- With no provider rows at all, the manager registers a single
localdriver rooted atSTORAGE_LOCAL_ROOT. - With provider rows, a
localdriver (rooted atSTORAGE_LOCAL_ROOT) is still registered next to them, unless a provider is itself namedlocal. It is always active and is the fallback default.
Uploads to `local` are not malware-scanned
Only a scan-gated S3 provider (malwareScan: true + rawBucket) puts uploads behind the malware scan gate. The implicit local driver does not. Uploads that name no storage go to the default provider, and when no provider is flagged isDefault that default is local.
Before deploying to an environment whose only configured provider is a scan-gated S3 provider, set that provider as Default (isDefault: true). Otherwise uploads fall back to local and bypass the malware scan.
Upload locations for clients
GET /files/storage-locations (any authenticated user) lists the storages that accept new uploads — active drivers only, the default first:
json
{ "data": ["s3-media", "local"] }With ?detailed=true:
json
{
"data": [
{ "name": "s3-media", "isDefault": true },
{ "name": "local", "isDefault": false }
]
}Endpoints
All endpoints below require Admin access.
GET /system/storage-providers
List all configured storage providers (sensitive fields masked). The implicit local driver is not listed — it has no row.
Response:
json
{
"data": [
{
"id": 1,
"name": "disk",
"extension_key": "system_storage_provider",
"value": {
"type": "local",
"root": "/var/uploads",
"isActive": true,
"isDefault": false
}
},
{
"id": 2,
"name": "s3-media",
"extension_key": "system_storage_provider",
"value": {
"type": "s3",
"bucket": "my-media-bucket",
"region": "us-east-1",
"accessKeyId": "********",
"secretAccessKey": "********",
"isActive": true,
"isDefault": true
}
}
]
}GET /system/storage-providers/:name
Get a specific provider by name.
URL Parameters:
name— Provider name
Response: { "data": { ...provider } } — a single provider object.
Error: 404 NOT_FOUND if provider does not exist.
POST /system/storage-providers
Create a new storage provider.
Request Body:
json
{
"name": "s3-archive",
"value": {
"type": "s3",
"bucket": "my-archive-bucket",
"region": "eu-west-1",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"isActive": true,
"isDefault": true
}
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Unique provider name (used in odp_files.storage) |
value | object | Yes | Driver configuration — see Driver Configurations |
Response: 201 Created
json
{
"data": { "id": 3 }
}Errors: 400 INVALID_PAYLOAD when name/value is missing or the flags are invalid.
Side Effects: with isDefault: true, every other provider's isDefault is cleared; then storageManager.initialize() reloads all providers.
POST /system/storage-providers/test
Test a provider config without saving or registering it. Used by the admin form's "Test connection" button.
Request Body:
json
{
"id": 2,
"value": {
"type": "s3",
"bucket": "my-media-bucket",
"region": "us-east-1",
"accessKeyId": "********",
"secretAccessKey": "********"
}
}| Field | Type | Required | Description |
|---|---|---|---|
value | object | Yes | The config to test (may be unsaved form values) |
id | number | string | No | Existing provider id. Its stored (decrypted) config is the base: value is merged over it, and accessKeyId / secretAccessKey sent as "********", "" or omitted are replaced by the stored secrets. 404 NOT_FOUND if the id does not exist |
What is probed (service/api/src/storage/test-connection.ts):
type | Checks |
|---|---|
s3 | Requires accessKeyId, secretAccessKey, bucket (else a config step failure MissingConfig). Writes a probe object .odp-connection-test/<uuid>.txt to bucket then runs put → head → delete (with aws:kms SSE when kmsKeyId is set, like real uploads). When malwareScan: true and rawBucket is set, the same probe runs on rawBucket too. The S3 client makes a single attempt (no retries) |
local | Resolves root (default ./uploads), then mkdir → write → stat → unlink a probe file .odp-connection-test-<uuid>.txt |
| other | config step failure UnknownType |
Each step has a 5 s timeout (CONNECTION_TEST_TIMEOUT_MS); a timeout is reported as code Timeout. The probe object is deleted on a best-effort basis if a later step fails.
Provider failures do not make the request fail: the response is always 200 and the outcome is in data. Credentials are never echoed back — any access key or secret appearing in a provider error message is replaced by ********.
Response: 200 OK
| Field | Description |
|---|---|
ok | true when every check passed |
message | Connection OK (<locations>) or Connection failed for <location>: <error> |
details.type | Tested driver type |
details.checks[] | One per target: target (bucket | rawBucket | root), location (bucket name or resolved path), ok, and on failure step (config, put, head, delete, mkdir, write, stat, unlink), code, error |
details.durationMs | Total test duration |
Success:
json
{
"data": {
"ok": true,
"message": "Connection OK (my-media-bucket, my-media-raw)",
"details": {
"type": "s3",
"checks": [
{ "target": "bucket", "location": "my-media-bucket", "ok": true },
{ "target": "rawBucket", "location": "my-media-raw", "ok": true }
],
"durationMs": 412
}
}
}Failure:
json
{
"data": {
"ok": false,
"message": "Connection failed for my-media-bucket: Access denied — the credentials lack s3:PutObject/GetObject/DeleteObject on this bucket (or the KMS key) (Access Denied)",
"details": {
"type": "s3",
"checks": [
{
"target": "bucket",
"location": "my-media-bucket",
"ok": false,
"step": "put",
"code": "AccessDenied",
"error": "Access denied — the credentials lack s3:PutObject/GetObject/DeleteObject on this bucket (or the KMS key) (Access Denied)"
}
],
"durationMs": 187
}
}
}Error codes that carry a hint in error: AccessDenied, NoSuchBucket, InvalidAccessKeyId, SignatureDoesNotMatch, PermanentRedirect, AuthorizationHeaderMalformed, Timeout, ENOTFOUND, ECONNREFUSED, EACCES, EROFS, ENOTDIR. Other codes are passed through with the raw provider message.
Errors (request-level): 400 INVALID_PAYLOAD when value is missing; 404 NOT_FOUND for an unknown id.
PATCH /system/storage-providers/:id
Update a storage provider's configuration.
URL Parameters:
id— Provider record ID (integer)
Request Body:
json
{
"value": {
"type": "s3",
"bucket": "updated-bucket",
"region": "us-west-2",
"accessKeyId": "********",
"secretAccessKey": "NEW_SECRET_KEY",
"isActive": true,
"isDefault": false
}
}value replaces the stored config as a whole — send every field, not just the changed ones. To keep an existing secret, send the masked value "********" for it.
Response:
json
{
"data": { "id": 3 }
}Errors:
400 INVALID_PAYLOAD—valuemissing, or invalid flags (includingisDefault: truewithisActive: false).409 CONFLICT— turningmalwareScanoff while files on this provider are stillpendinga scan.
Side Effects: with isDefault: true, every other provider's isDefault is cleared; then storageManager.initialize() reloads all providers.
To deactivate the current default, send
isActive: falsewithisDefault: false(or withoutisDefault). New uploads then go to the next provider in the default resolution order.
DELETE /system/storage-providers/:id
Delete a storage provider.
URL Parameters:
id— Provider record ID
Response: 204 No Content
Side Effect: storageManager.initialize() reloads providers. Files that referenced this provider by name will fail to serve. To stop new uploads while keeping existing files served, set isActive: false instead.
Driver Configurations
Common fields for every driver: type, and the optional isActive / isDefault flags.
Local Driver
json
{
"type": "local",
"root": "/var/uploads"
}| Field | Required | Description |
|---|---|---|
type | Yes | Must be local |
root | No | Storage directory. Defaults to ./uploads; created if it does not exist |
S3 Driver
json
{
"type": "s3",
"bucket": "my-bucket",
"region": "us-east-1",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"endpoint": "https://minio.example.com",
"kmsKeyId": "arn:aws:kms:us-east-1:111122223333:key/example",
"malwareScan": true,
"rawBucket": "my-bucket-raw"
}| Field | Required | Description |
|---|---|---|
type | Yes | Must be s3 |
bucket | Yes | S3 bucket name. For a scan-gated provider this is the CLEANED (serving) bucket |
accessKeyId | Yes | Access key ID (encrypted at rest) |
secretAccessKey | Yes | Secret access key (encrypted at rest) |
region | No | AWS region (default us-east-1) |
endpoint | No | Custom endpoint URL (MinIO, Backblaze, ...). When set, path-style URLs are used |
kmsKeyId | No | KMS key for aws:kms server-side encryption |
malwareScan | No | true + rawBucket = scan-gated provider: uploads are written to rawBucket and only served from bucket once scanned clean |
rawBucket | No | RAW (upload) bucket for a scan-gated provider |
A provider missing accessKeyId, secretAccessKey or bucket is skipped at initialization (warning logged) and is not available.
Storage Manager
The StorageManager (service/api/src/storage/manager.ts) is a singleton that manages driver instances. When initialize() is called:
- Reads all
system_storage_providersettings from the database (ordered byid) - Decrypts sensitive fields
- Reads the
isActive/isDefaultflags and instantiates drivers (local, S3, or scan-gated S3). Inactive providers are registered too, marked closed to uploads - Registers the implicit
localdriver (see above) - Swaps the new registry in atomically, so requests never see a half-built one
Drivers are then available via storageManager.getDriver(name); new uploads resolve their target through storageManager.resolveUploadStorage(name).
Data Model
Storage providers are stored in odp_extension_settings:
odp_extension_settings (storage providers)
| Column | Value/Description |
|---|---|
extension_key | system_storage_provider |
name | Provider name (e.g., disk, s3-media) |
value | JSON config (including isActive / isDefault) with encrypted sensitive fields |
Environment Variables
| Variable | Default | Description |
|---|---|---|
STORAGE_LOCAL_ROOT | ./uploads | Root of the implicit local driver |
SECRET | — | Used for encrypting sensitive fields |