Storage Service (PPP Backend)
This document explains how PPP backend code targets object storage and how storage object keys are built.
Storage is provider-selected via STORAGE_PROVIDER — exactly one of two implementations is active at a time, never a silent fallback (ADR-0006, superseding ADR-0002):
azure-blob— Azure Blob Storage (AzureBlobProvider). The legacy provider, used by any environment still running on Azure Container Apps.filesystem— NAS-hosted filesystem storage (FilesystemStorageProvider), backing PPP's Synology NAS deployment. Seedeploy/nas/docker-compose.nas.ymland ADR-0006 (docs/site/architecture/decisions/0006-nas-hosted-storage-and-runtime.md) for the migration this supports.
createStorageProvider() throws if STORAGE_PROVIDER is unset or unrecognised — there is no default to silently fall back to.
Environment Variables
Common
STORAGE_PROVIDER- Selects the backing store:
azure-bloborfilesystem. Required — no default.
- Selects the backing store:
STORAGE_KEY_PREFIX- Optional prefix applied to all storage object keys (e.g.
ppp-devto isolate environments in a shared account/volume). Applied identically by both providers via the sharedapplyKeyPrefixhelper.
- Optional prefix applied to all storage object keys (e.g.
azure-blob
AZURE_STORAGE_ACCOUNT- Azure Storage account name (required).
AZURE_STORAGE_CONTAINER- Blob container name (required).
AZURE_STORAGE_ACCOUNT_KEY- Shared-key credential used to sign SAS URLs. Alternatively set
AZURE_STORAGE_CONNECTION_STRING. If neither is present, the provider falls back toDefaultAzureCredential(Managed Identity in Azure Container Apps) and uses a user-delegation key for SAS.
- Shared-key credential used to sign SAS URLs. Alternatively set
filesystem
STORAGE_OBJECTS_ROOT- Absolute path to the write root on disk (required). On the NAS deployment this is the bind-mounted
ppp-objectsvolume (/data/objectsinside the container).
- Absolute path to the write root on disk (required). On the NAS deployment this is the bind-mounted
STORAGE_SIGNING_SECRET- HMAC-SHA256 secret used to sign the time-limited tokens
getSignedReadUrl/getSignedUploadUrlmint in place of an Azure SAS query string (required). Env-first, same convention asCPD_APPROVAL_SECRET.
- HMAC-SHA256 secret used to sign the time-limited tokens
API_BASE_URL- This backend's own externally-reachable base URL, used to build the signed-URL host (e.g. the Cloudflare Tunnel hostname). Not
WEB_APP_BASE_URL, which is the frontend's URL.
- This backend's own externally-reachable base URL, used to build the signed-URL host (e.g. the Cloudflare Tunnel hostname). Not
Key Prefixing Rules
All storage keys go through a single normalization step, identical for both providers:
- If
STORAGE_KEY_PREFIXis set, the prefix is prepended to every key. - The prefix is idempotent (a key already containing it will not be double-prefixed).
- If the key uses the public namespace, the prefix is applied after
public/.
Examples (with STORAGE_KEY_PREFIX=ppp-dev):
input key: ppp/cpd_activity_files/file.pdf
stored key: ppp-dev/ppp/cpd_activity_files/file.pdf
input key: public/ppp/cv/123_file.pdf
stored key: public/ppp-dev/ppp/cv/123_file.pdfSigned Upload/Read URLs
azure-blob — Azure SAS
Upload URLs are short-lived Azure Blob SAS URLs (create/write permission, ~5 minutes) scoped to the public namespace:
- Requested key:
ppp/cpd_activity_files/file.pdf - Signed key:
public/<prefix>/ppp/cpd_activity_files/file.pdf
The client uploads with an HTTP PUT to the SAS URL and must send the x-ms-blob-type: BlockBlob header. Signed read URLs default to a 1-hour expiry; Passport-scoped blobs are capped at 15 minutes.
Credential resolution order: AZURE_STORAGE_CONNECTION_STRING if set, else AZURE_STORAGE_ACCOUNT_KEY via StorageSharedKeyCredential, else DefaultAzureCredential (Managed Identity, no static key required).
filesystem — self-issued HMAC tokens
A filesystem has no native SAS equivalent, so FilesystemStorageProvider mints its own signed URL: an HMAC-SHA256-signed, time-limited token verified by a route this same backend serves — GET /storage/signed/:token for reads, PUT /storage/signed/:token for uploads. Same expiry conventions as Azure (5 min upload / 1 hour read / 15 min Passport-scoped) and the same public/-prefixing convention for upload keys, so callers see identical behaviour across providers. The route is only registered when STORAGE_PROVIDER=filesystem — it does not exist in the Azure-hosted image.
The frontend's existing x-ms-blob-type: BlockBlob upload header (instances/ppp/src/utils/storageClient.ts) is Azure-specific but harmless against this route — it is silently ignored.
Related Code
packages/backend-ppp-core/src/utils/storage/azure-blob-provider.ts— Azure Blob provider (SAS, upload/read/delete, key normalization)packages/backend-ppp-core/src/utils/storage/filesystem-provider.ts— NAS-hosted filesystem provider (HMAC-signed URLs, path-traversal guard)packages/backend-ppp-core/src/utils/storage/index.ts—createStorageProvider(selects provider fromSTORAGE_PROVIDER, no default)api/backend-ppp/entrypoints/api-container.ts— registers the/storage/signed/:tokenroute whenSTORAGE_PROVIDER=filesystemapi/backend-core/src/services/core/StorageService/index.ts