Add deployment example for directory cache

deployment-examples/docker-compose/README.md

@@ -265,6 +265,95 @@
   --jobs=50  # High parallelism to distribute across workers
 ```
 
+## Performance Optimization: Directory Cache
+
+### What is the Directory Cache?
+
+The directory cache dramatically improves build performance by caching input directories and reusing them via hardlinks instead of copying files. This provides **~100x faster directory preparation** for subsequent builds.
+
+### Enabling Directory Cache
+
+Add the `directory_cache` configuration to your worker configuration:
+
+```json5
+{
+  workers: [
+    {
+      local: {
+        work_directory: "/root/.cache/nativelink/work",
+
+        // Add directory cache for ~100x faster builds
+        directory_cache: {
+          max_entries: 1000,        // Maximum cached directories
+          max_size_bytes: "10GB",   // Maximum cache size
+        },
+
+        // ... rest of worker config
+      }
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+- **`max_entries`** (default: 1000): Maximum number of cached directories
+- **`max_size_bytes`** (default: "10GB"): Maximum total cache size (supports "10GB", "1TB", etc.)
+- **`cache_root`** (optional): Custom cache location (defaults to `{work_directory}/../directory_cache`)
+
+### Docker Compose Volume Configuration
+
+When using directory cache with Docker, ensure cache persistence:
+
+```yaml
+services:
+  worker:
+    volumes:
+      - worker-work:/root/.cache/nativelink/work
+      - worker-cache:/root/.cache/nativelink/directory_cache  # Persist cache
+
+volumes:
+  worker-work:
+  worker-cache:  # Dedicated volume for directory cache
+```
+
+### Performance Expectations
+
+- **First build**: No benefit (cache is empty)
+- **Subsequent builds**: ~100x faster directory preparation
+- **Best for**: Incremental builds, large dependency trees, CI/CD pipelines, monorepos
+
+### Important: Same Filesystem Requirement
+
+The cache directory **must be on the same filesystem** as the work directory for hardlinks to work. In Docker, this typically means:
+
+✅ **Correct**: Both on the same volume or bind mount
+```yaml
+volumes:
+  - /data/nativelink:/root/.cache/nativelink  # Cache and work are under same path
+```
+
+❌ **Incorrect**: Separate volumes
+```yaml
+volumes:
+  - /data/work:/root/.cache/nativelink/work
+  - /data/cache:/root/.cache/nativelink/directory_cache  # Different filesystem
+```
+
+### Monitoring Cache Performance
+
+Enable debug logging to monitor cache effectiveness:
+```sh
+# View cache hits/misses in logs
+docker-compose logs -f worker | grep "Directory cache"
+```
+
+Output will show:
+```
+DEBUG Directory cache HIT digest=abc123...
+DEBUG Directory cache MISS digest=def456...
+```
+
 ## Production Considerations
 
 For production deployments:
@@ -273,5 +362,6 @@
 3. Use external storage (NFS, S3, etc.) for CAS
 4. Monitor worker metrics
 5. Set up log aggregation
+6. **Enable directory cache** for significant performance gains
 
 See [Kubernetes deployment](../kubernetes/) for production-grade configurations.

deployment-examples/docker-compose/worker-shared-cas.json5

@@ -60,6 +60,14 @@
           ac_store: "GRPC_LOCAL_AC_STORE",
         },
         work_directory: "/root/.cache/nativelink/work",
+
+        // Optional: Enable directory cache for ~100x faster builds
+        // Uncomment to enable:
+        // directory_cache: {
+        //   max_entries: 1000,
+        //   max_size_bytes: "10GB",
+        // },
+
         platform_properties: {
           cpu_count: {
             query_cmd: "nproc",

deployment-examples/docker-compose/worker.json5

@@ -61,6 +61,14 @@
           ac_store: "GRPC_LOCAL_AC_STORE",
         },
         work_directory: "/root/.cache/nativelink/work",
+
+        // Optional: Enable directory cache for ~100x faster builds
+        // Uncomment to enable:
+        // directory_cache: {
+        //   max_entries: 1000,
+        //   max_size_bytes: "10GB",
+        // },
+
         platform_properties: {
           cpu_count: {
             query_cmd: "nproc",

web/platform/src/content/docs/docs/config/basic-configs.mdx

@@ -17,6 +17,12 @@ The recommended configuration of the basic CAS is actually based on a real
 production configuration, just arranged as the all-in-one Config and using
 memory and filesystem stores instead of S3 and Redis.
 
+:::tip
+For significantly faster builds (~100x speedup on directory preparation), consider
+enabling the [directory cache](/docs/deployment-examples/directory-cache) feature.
+The examples below include commented-out directory cache configurations you can enable.
+:::
+
 ## Basic CAS Configuration
 
 ```json5
@@ -94,6 +100,12 @@ memory and filesystem stores instead of S3 and Redis.
         "ac_store": "AC_MAIN_STORE",
       },
       "work_directory": "/tmp/nativelink/work",
+      // Optional: Enable directory caching for faster builds (~100x speedup)
+      // See: /docs/deployment-examples/directory-cache for details
+      // "directory_cache": {
+      //   "max_entries": 1000,
+      //   "max_size_bytes": "10GB",
+      // },
       "platform_properties": {
         "cpu_count": {
           "values": ["16"],
@@ -265,6 +277,12 @@ memory and filesystem stores instead of S3 and Redis.
         "ac_store": "AC_MAIN_STORE",
       },
       "work_directory": "/tmp/nativelink/work",
+      // Optional: Enable directory caching for faster builds (~100x speedup)
+      // See: /docs/deployment-examples/directory-cache for details
+      // "directory_cache": {
+      //   "max_entries": 1000,
+      //   "max_size_bytes": "10GB",
+      // },
       "platform_properties": {
         "cpu_count": {
           "values": ["16"],