Umbraco LuceneDirectoryFactory and LocalTempStorageLocation Lookup

umbraco_hosting_examine_en.md

Umbraco -- Matrix: what to set per environment (Examine + temp)

This guide is a quick lookup matrix for:

• Umbraco:CMS:Examine:LuceneDirectoryFactory
• Umbraco:CMS:Hosting:LocalTempStorageLocation

---

Official Documentation

• Examine & indexing:
  https://docs.umbraco.com/umbraco-cms/reference/searching/examine
• Examine settings (Lucene directory factories):
  https://docs.umbraco.com/umbraco-cms/reference/configuration/examinesettings
• Hosting & temp storage:
  https://docs.umbraco.com/umbraco-cms/reference/configuration/hostingsettings
• Load balancing guidance:
  https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/load-balancing

---

Rule of thumb

• On-prem single instance: Default / Default
• Azure App Service: EnvironmentTemp + (SyncedTemp... for single/admin, Temp... for public scale-out)
• On-prem load balanced: usually EnvironmentTemp + Temp... on CD (local indexes per node)

---

Why this matters

Understanding these settings is critical because they directly impact:

1) Index stability

Lucene indexes rely on file locks. If multiple nodes attempt to write to the same physical directory (shared or replicated TEMP), you risk:

• File locking exceptions
• Corrupt indexes
• Random search failures
• Performance degradation

Keeping indexes local per node avoids cross-machine locking conflicts.

---

2) Azure ephemeral storage behavior

On Azure App Service:

• The machine can be recycled at any time.
• The %TEMP% directory is local to the instance.
• Local disk may be cleared on restart or scale operations.

Using SyncedTempFileSystemDirectoryFactory ensures:

• Index runs in fast local temp storage
• Index is synced back to umbraco/Data/TEMP/ExamineIndexes
• Index can be restored after app restart

Without this, indexes may rebuild frequently, increasing cold start time.

---

3) Load-balanced environments

In CM + CD setups:

• CM writes and rebuilds indexes.
• CD nodes should avoid syncing indexes back if storage is shared or replicated.
• Each CD should ideally maintain its own local index copy.

This prevents file replication loops and locking conflicts.

---

Matrix: what to set per environment

---

Scenario LuceneDirectoryFactory LocalTempStorageLocation Notes / rationale

---

1) On-prem, single Default Default Simple setup. Indexes live under instance (CM+CD in same umbraco/Data/TEMP/ExamineIndexes. instance)

2) Azure App Service, SyncedTempFileSystemDirectoryFactory EnvironmentTemp Index runs from machine temp and is single instance (CM+CD synced back to disk for restore after in same instance) recycle.

3) Azure App Service Admin: EnvironmentTemp Admin single instance, Public "load-balanced-ish" SyncedTempFileSystemDirectoryFactory scalable. Public: TempFileSystemDirectoryFactory

4) On-prem load CM: EnvironmentTemp Avoid shared index locking issues. balanced (CM + multiple SyncedTempFileSystemDirectoryFactory
CD) CD: TempFileSystemDirectoryFactory

Configuration Examples

On-prem single instance

{
  "Umbraco": {
    "CMS": {
      "Hosting": { "LocalTempStorageLocation": "Default" },
      "Examine": { "LuceneDirectoryFactory": "Default" }
    }
  }
}

---

Azure single instance

{
  "Umbraco": {
    "CMS": {
      "Hosting": { "LocalTempStorageLocation": "EnvironmentTemp" },
      "Examine": { "LuceneDirectoryFactory": "SyncedTempFileSystemDirectoryFactory" }
    }
  }
}

---

Azure load balanced

Admin:

{
  "Umbraco": {
    "CMS": {
      "Hosting": { "LocalTempStorageLocation": "EnvironmentTemp" },
      "Examine": { "LuceneDirectoryFactory": "SyncedTempFileSystemDirectoryFactory" }
    }
  }
}

Public:

{
  "Umbraco": {
    "CMS": {
      "Hosting": { "LocalTempStorageLocation": "EnvironmentTemp" },
      "Examine": { "LuceneDirectoryFactory": "TempFileSystemDirectoryFactory" }
    }
  }
}

---

On-prem CM + multiple CD

CM:

{
  "Umbraco": {
    "CMS": {
      "Hosting": { "LocalTempStorageLocation": "EnvironmentTemp" },
      "Examine": { "LuceneDirectoryFactory": "SyncedTempFileSystemDirectoryFactory" }
    }
  }
}

CD:

{
  "Umbraco": {
    "CMS": {
      "Hosting": { "LocalTempStorageLocation": "EnvironmentTemp" },
      "Examine": { "LuceneDirectoryFactory": "TempFileSystemDirectoryFactory" }
    }
  }
}

---

Final Recommendation

When in doubt:

• Never share Lucene index directories between nodes.
• Prefer local temp storage per machine.
• Only sync back to disk when you need persistence across restarts (Azure single/admin).