Storage back ends
Each storage back end is configured under dari/storage/{name} in your Dari settings, where {name} is an arbitrary identifier you choose. Set dari/defaultStorage to the name of the back end you want to use by default.
Common settings
All back ends that extend AbstractStorageItem support these settings:
| Setting | Description |
|---|---|
class | Fully qualified class name of the StorageItem implementation. |
baseUrl | Base URL for constructing public URLs. |
secureBaseUrl | Base URL for constructing secure (HTTPS) public URLs. |
baseUrls | Map of multiple base URLs for multi-CDN distribution. |
secureBaseUrls | Map of multiple secure base URLs for multi-CDN distribution. |
hashAlgorithm | Name of the StorageItemHash to use for distributing requests across baseUrls. |
originBaseUrl | Base URL for constructing origin URLs (bypasses CDN). |
When both baseUrl and baseUrls are set, baseUrl takes precedence. Use baseUrls with hashAlgorithm for multi-CDN setups where you want to distribute assets across multiple domains.
Local filesystem
Stores files directly on the server's filesystem. Useful for development and single-server deployments.
Class: com.psddev.dari.util.LocalStorageItem
| Setting | Required | Description |
|---|---|---|
rootPath | Yes | Absolute path to the directory where files are stored. |
originBaseUrl | No | Base URL for origin access. |
Example configuration:
1dari/defaultStorage=local2dari/storage/local/class=com.psddev.dari.util.LocalStorageItem3dari/storage/local/rootPath=/servers/tomcat/storage4dari/storage/local/baseUrl=http://localhost/storage
Amazon S3
Stores files in an Amazon S3 bucket using the AWS SDK v2.
Class: com.psddev.dari.aws.S3StorageItem
Artifact: com.brightspot.storage:aws
| Setting | Required | Description |
|---|---|---|
bucket | Yes | S3 bucket name. Can include a path prefix (e.g., my-bucket/prefix). |
cannedACL | No | The ObjectCannedACL to apply to uploaded objects. Defaults to PUBLIC_READ. |
originBaseUrl | No | Base URL for origin access (bypasses CDN). |
Example configuration:
1dari/defaultStorage=s32dari/storage/s3/class=com.psddev.dari.aws.S3StorageItem3dari/storage/s3/bucket=my-bucket4dari/storage/s3/baseUrl=https://cdn.example.com5dari/storage/s3/secureBaseUrl=https://cdn.example.com
AWS credentials are resolved using the default credential provider chain. You do not need to configure access keys in Dari settings—use environment variables, IAM roles, or shared credential files instead.
Bucket path prefix
The bucket setting supports a path prefix separated by /. For example, my-bucket/media stores all files under the media/ prefix within my-bucket.
Access control
The cannedACL setting accepts any value from software.amazon.awssdk.services.s3.model.ObjectCannedACL:
PUBLIC_READ(default)PRIVATEAUTHENTICATED_READBUCKET_OWNER_FULL_CONTROLBUCKET_OWNER_READAWS_EXEC_READ
You can also change permissions on individual objects programmatically:
1storageItem.updatePermission(true); // make private2storageItem.updatePermission(false); // make public
Azure Blob Storage
Stores files in Azure Blob Storage containers.
Class: com.psddev.azure.storage.AzureBlobStorageItem
Artifact: com.brightspot.storage:azure
| Setting | Required | Description |
|---|---|---|
accountName | Yes* | Azure storage account name. Required unless endpoint is set. |
accountKey | No | Azure storage account key. If omitted, uses DefaultAzureCredential. |
container | Yes | Name of the blob container. Created automatically if it doesn't exist. |
endpoint | No | Custom endpoint URL. Overrides the default https://{accountName}.blob.core.windows.net/ endpoint. |
disablePublicRead | No | Set to true to disable public blob-level read access. Defaults to false. |
originBaseUrl | No | Base URL for origin access. |
Example configuration:
1dari/defaultStorage=azure2dari/storage/azure/class=com.psddev.azure.storage.AzureBlobStorageItem3dari/storage/azure/accountName=mystorageaccount4dari/storage/azure/container=media5dari/storage/azure/baseUrl=https://cdn.example.com
When accountKey is omitted, the Azure SDK's DefaultAzureCredential is used, which supports managed identities, environment variables, and other credential sources.
Azure Blob Storage does not support per-object ACL changes. Calling updatePermission() on an AzureBlobStorageItem throws UnsupportedOperationException. Access control is managed at the container level via the disablePublicRead setting.
Google Cloud Storage
Stores files in Google Cloud Storage buckets.
Class: com.psddev.google.storage.GoogleCloudStorageItem
Artifact: com.brightspot.storage:gcp
| Setting | Required | Description |
|---|---|---|
bucketName | Yes | Name of the GCS bucket. |
credentialsFile | No | Path to a service account JSON credentials file. If omitted, uses Application Default Credentials. |
predefinedAcl | No | The PredefinedAcl to apply to uploaded objects. Defaults to PUBLIC_READ. |
uniformBucketLevelAccess | No | Set to true when the bucket uses uniform bucket-level access. Disables per-object ACL. |
Example configuration:
1dari/defaultStorage=gcs2dari/storage/gcs/class=com.psddev.google.storage.GoogleCloudStorageItem3dari/storage/gcs/bucketName=my-media-bucket4dari/storage/gcs/baseUrl=https://cdn.example.com5dari/storage/gcs/secureBaseUrl=https://cdn.example.com
Uniform bucket-level access
When uniformBucketLevelAccess is true, per-object ACLs are not set during upload. Access is controlled entirely by IAM policies on the bucket. This is the recommended approach for new GCS buckets.
Multi-CDN hashing
To distribute assets across multiple CDN domains, configure multiple base URLs and a hashing algorithm:
1dari/storage/s3/baseUrls/1=https://cdn1.example.com2dari/storage/s3/baseUrls/2=https://cdn2.example.com3dari/storage/s3/baseUrls/3=https://cdn3.example.com4dari/storage/s3/hashAlgorithm=_pathHashCode
The built-in _pathHashCode algorithm distributes files across base URLs by hashing the file path. You can implement StorageItemHash to provide a custom hashing strategy. See Extending—Custom hashing for details.