Orchardcore AI Documents Azure Storage

Orchard Core AI Documents Azure Blob Storage

Configure Azure Blob document storage

You are an Orchard Core expert. Configure CrestApps AI Documents to place uploaded document files in Azure Blob Storage while preserving the normal document extraction, chunking, embedding, indexing, and RAG workflow.

Guidelines

• Enable the exact feature ID CrestApps.OrchardCore.AI.Documents.Azure.
• This feature depends on AI Documents through ChatInteractionsConstants.Feature.ChatDocuments; it enables the base document capability by dependency rather than replacing its processing pipeline.
• The feature changes only the IDocumentFileStore implementation. It does not create an index, generate embeddings, or select a vector-search backend.
• If either ConnectionString or ContainerName is empty, the feature logs an error and leaves the existing IDocumentFileStore registration unchanged rather than registering the Azure-backed replacement.
• Install CrestApps.OrchardCore.AI.Documents.Azure in the web or startup project.
• Keep connection strings in user secrets, environment variables, managed identity configuration, or a production secret store; never place production keys in recipes or source control.
• Use a lowercase Azure-valid container name. Configuration normalizes the container name to lowercase.
• Treat the container lifecycle options carefully for multi-tenant installations, especially if tenants share one container.

What the feature registers

AIDocumentBlobStorageOptions derives from MediaBlobStorageOptionsBase. Its storage settings therefore include the connection string, container name, base path, create, and removal behavior.

Enable the feature

Enable an AI Documents context or indexing backend as appropriate, then enable Azure document storage. The base AI Documents capability is enabled by dependency.

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI.Documents.ChatInteractions",
        "CrestApps.OrchardCore.AI.Documents.Azure",
        "CrestApps.OrchardCore.AI.Documents.AzureAI"
      ],
      "disable": []
    }
  ]
}

The storage feature can also be used with CrestApps.OrchardCore.AI.Documents.Elasticsearch, Profiles, or Chat Sessions. Do not enable a search provider merely to use Blob Storage unless the application also needs indexed retrieval.

Configure tenant settings

Configure the tenant under OrchardCore:CrestApps:AI:AzureDocuments.

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "AzureDocuments": {
          "ConnectionString": "Use a secret or environment-variable value here",
          "ContainerName": "ai-documents",
          "BasePath": "tenants/default/documents",
          "CreateContainer": true,
          "RemoveContainer": false,
          "RemoveFilesFromBasePath": true
        }
      }
    }
  }
}

RemoveContainer takes precedence over RemoveFilesFromBasePath. Never enable RemoveContainer for a container shared by tenants or other applications.

Tenant lifecycle behavior

AIDocumentBlobContainerTenantEvents runs only when valid storage options are present. On activation, it skips uninitialized tenants and creates the configured container only when CreateContainer is true. The container is created without public access.

On tenant removal:

1. If RemoveContainer is true, it deletes the whole configured container.
2. Otherwise, if RemoveFilesFromBasePath is true, it enumerates blobs with the base path prefix and deletes each blob.
3. Azure request failures are logged and are surfaced through the tenant removal context so the administrator can act on the failed cleanup.

Choose a unique container per tenant when whole-container cleanup is desired. Choose a tenant-specific BasePath and RemoveFilesFromBasePath when tenants share a container.

Storage flow

1. A user uploads a document through a supported AI Documents context.
2. IDocumentFileStore writes the file through DefaultDocumentFileStore.
3. With valid Azure settings, that wrapper uses BlobFileStore; otherwise this module does not replace the application's existing document-file-store registration.
4. The usual document processor extracts text, chunks it, and optionally indexes the resulting chunks through the enabled search backend.

Blob Storage does not make a file publicly accessible and does not alter authorization for upload, download, or document removal.

Example deployment layout

For a shared account and container, isolate tenants by path:

{
  "OrchardCore": {
    "CrestApps": {
      "AI": {
        "AzureDocuments": {
          "ConnectionString": "Set through a production secret provider",
          "ContainerName": "ai-documents",
          "BasePath": "tenants/{ ShellName }/documents",
          "CreateContainer": true,
          "RemoveContainer": false,
          "RemoveFilesFromBasePath": true
        }
      }
    }
  }
}

Verify the shell-token syntax and the resolved path for the Orchard Core version in use before relying on it for retention isolation.

Troubleshooting

Security checklist

• Grant the storage identity only the blob permissions needed for the selected lifecycle options.
• Prefer private endpoints and encrypted transport for production storage accounts.
• Keep blob containers private; this module creates containers with PublicAccessType.None.
• Establish retention and tenant-deletion policy before setting cleanup flags.