feat: add --read-only mode for serving on read-only filesystems (AKS/K8s)

New --read-only flag on serve command for deployments with read-only
volumes (e.g., AKS, K8s with read-only root filesystem):

  code-iq serve /data --read-only

What it does:
- Neo4j: opens in read-only mode (GraphDatabaseSettings.read_only_database_default)
  — no lock files, no transaction logs, no store_lock created
- H2: opens with ACCESS_MODE_DATA=r and FILE_LOCK=NO
  — no lock files, no writes
- GraphBootstrapper: skipped entirely (no H2→Neo4j bootstrap writes)

Configuration:
- codeiq.read-only=true in application.yml or --read-only CLI flag
- Only affects serving profile — indexing/enriching always need write access

For AKS deployment:
  1. index + enrich on writable storage (CI or local)
  2. bundle the .code-iq/ directory into container image
  3. serve --read-only on AKS with read-only filesystem

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aksOps

src/main/java/io/github/randomcodespace/iq/cache/AnalysisCache.java

@@ -112,17 +112,37 @@ CREATE TABLE IF NOT EXISTS analysis_runs (
      * @param dbPath path to the H2 database file (without extension)
      */
     public AnalysisCache(Path dbPath) {
+        this(dbPath, false);
+    }
+
+    /**
+     * Open an analysis cache. In read-only mode, no lock files are created
+     * and no writes are allowed — suitable for read-only filesystems (AKS/K8s).
+     *
+     * @param dbPath   path to the H2 database file (without extension)
+     * @param readOnly if true, opens DB in read-only mode (no lock files, no writes)
+     */
+    public AnalysisCache(Path dbPath, boolean readOnly) {
         this.dbPath = dbPath;
         try {
-            Files.createDirectories(dbPath.getParent());
+            if (!readOnly) {
+                Files.createDirectories(dbPath.getParent());
+            }
             // Strip .db extension if present — H2 appends its own .mv.db
             String dbFile = dbPath.toString();
             if (dbFile.endsWith(".db")) {
                 dbFile = dbFile.substring(0, dbFile.length() - 3);
             }
-            this.conn = DriverManager.getConnection(
-                    "jdbc:h2:file:" + dbFile + ";AUTO_SERVER=FALSE;MODE=MySQL;DB_CLOSE_ON_EXIT=FALSE;WRITE_DELAY=0");
-            initDb();
+            String url = "jdbc:h2:file:" + dbFile + ";AUTO_SERVER=FALSE;MODE=MySQL;DB_CLOSE_ON_EXIT=FALSE";
+            if (readOnly) {
+                url += ";ACCESS_MODE_DATA=r;FILE_LOCK=NO";
+            } else {
+                url += ";WRITE_DELAY=0";
+            }
+            this.conn = DriverManager.getConnection(url);
+            if (!readOnly) {
+                initDb();
+            }
         } catch (Exception e) {
             throw new RuntimeException("Failed to open analysis cache at " + dbPath, e);
         }

src/main/java/io/github/randomcodespace/iq/cli/ServeCommand.java

@@ -46,6 +46,10 @@ public class ServeCommand implements Callable<Integer> {
             description = "Disable the web UI (React SPA). API and MCP endpoints remain active.")
     private boolean noUi;
 
+    @Option(names = {"--read-only"}, defaultValue = "false",
+            description = "Read-only mode: no lock files, no writes. For read-only filesystems (AKS/K8s).")
+    private boolean readOnly;
+
     @Autowired
     private CodeIqConfig config;
 
@@ -56,6 +60,9 @@ public class ServeCommand implements Callable<Integer> {
     public Integer call() {
         Path root = path.toAbsolutePath().normalize();
         config.setRootPath(root.toString());
+        if (readOnly) {
+            config.setReadOnly(true);
+        }
         NumberFormat nf = NumberFormat.getIntegerInstance(Locale.US);
 
         // Report Neo4j graph status

src/main/java/io/github/randomcodespace/iq/config/CodeIqConfig.java

@@ -51,6 +51,9 @@ public static class Graph {
         public void setPath(String path) { this.path = path; }
     }
 
+    /** Read-only mode for serving — no lock files, no writes. For read-only filesystems (AKS). */
+    private boolean readOnly = false;
+
     /** Service name tag for multi-repo graph mode. */
     private String serviceName;
 
@@ -104,6 +107,14 @@ public void setBatchSize(int batchSize) {
         this.batchSize = Math.max(1, batchSize);
     }
 
+    public boolean isReadOnly() {
+        return readOnly;
+    }
+
+    public void setReadOnly(boolean readOnly) {
+        this.readOnly = readOnly;
+    }
+
     public String getServiceName() {
         return serviceName;
     }

src/main/java/io/github/randomcodespace/iq/config/GraphBootstrapper.java

@@ -45,6 +45,12 @@ public GraphBootstrapper(GraphStore graphStore, CodeIqConfig config) {
 
     @EventListener(ApplicationReadyEvent.class)
     public void bootstrapNeo4jFromCache() {
+        // Skip bootstrap in read-only mode (no writes allowed)
+        if (config.isReadOnly()) {
+            log.info("Read-only mode -- skipping H2→Neo4j bootstrap");
+            return;
+        }
+
         // Check if Neo4j already has data
         long existingCount = graphStore.count();
         if (existingCount > 0) {

src/main/java/io/github/randomcodespace/iq/config/Neo4jConfig.java

@@ -1,5 +1,6 @@
 package io.github.randomcodespace.iq.config;
 
+import org.neo4j.configuration.GraphDatabaseSettings;
 import org.neo4j.configuration.connectors.BoltConnector;
 import org.neo4j.configuration.helpers.SocketAddress;
 import org.neo4j.dbms.api.DatabaseManagementService;
@@ -12,9 +13,11 @@
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.core.env.Environment;
 import org.springframework.data.neo4j.repository.config.EnableNeo4jRepositories;
 
 import java.nio.file.Path;
+import java.util.Arrays;
 
 /**
  * Neo4j Embedded configuration.
@@ -34,11 +37,19 @@ public class Neo4jConfig {
     private int boltPort;
 
     @Bean(destroyMethod = "shutdown")
-    DatabaseManagementService databaseManagementService(CodeIqConfig config) {
-        return new DatabaseManagementServiceBuilder(Path.of(config.getGraph().getPath()))
+    DatabaseManagementService databaseManagementService(CodeIqConfig config, Environment env) {
+        var builder = new DatabaseManagementServiceBuilder(Path.of(config.getGraph().getPath()))
                 .setConfig(BoltConnector.enabled, true)
-                .setConfig(BoltConnector.listen_address, new SocketAddress("localhost", boltPort))
-                .build();
+                .setConfig(BoltConnector.listen_address, new SocketAddress("localhost", boltPort));
+
+        // Read-only mode for serving profile — no lock files, no transaction logs.
+        // Required for read-only filesystems (e.g., AKS with read-only volumes).
+        boolean isServing = Arrays.asList(env.getActiveProfiles()).contains("serving");
+        if (isServing && config.isReadOnly()) {
+            builder.setConfig(GraphDatabaseSettings.read_only_database_default, true);
+        }
+
+        return builder.build();
     }
 
     @Bean