docs: documenting persistent dev mode

docs/src/modules/java-protobuf/pages/running-locally.adoc

@@ -123,7 +123,20 @@ grpcurl ^
 
 == Shut down the service
 
-Use `Ctrl+C` to shut down the service. When stopping your service, it will also shutdown the Kalix Runtime container and any other container you have defined in `docker-compose.yml`. Unless you have chosen to start `docker-compose` manually in a separate terminal, in which case you will need to stop it manually as well. 
+Use `Ctrl+C` to shut down the service. When stopping your service, it will also shutdown the Kalix Runtime container and any other container you have defined in `docker-compose.yml`. Unless you have chosen to start `docker-compose` manually in a separate terminal, in which case you will need to stop it manually as well.
+
+== Running service with persistence enabled
+
+By default, Kalix services are configured to run with disabled persistence. This means that the Kalix Runtime will use an in-memory database to store the state of your service. This is useful for local development since it allows you to quickly start and stop your service without having to worry about cleaning up the database.
+
+However, if you want to run your service with persistence enabled, you can do so by changing the `docker-compose` file as below.
+
+[source, dockerfile, indent=0]
+----
+include::example$scala-protobuf-doc-snippets/docker-compose.yml[tag=persistence-mode]
+----
+<1> Maps local directory to the Kalix Runtime database directory `/var/kalix`.
+<2> Sets `PERSISTENCE_ENABLED` env to `true`.
 
 == Running multiple services locally
 

docs/src/modules/java/pages/running-locally.adoc

@@ -87,6 +87,19 @@ curl -XGET localhost:9000/customer/one
 
 Use `Ctrl+C` to shut down the service. When stopping your service, it will also shutdown the Kalix Runtime container and any other container you have defined in `docker-compose.yml`. Unless you have chosen to start `docker-compose` manually in a separate terminal, in which case you will need to stop it manually as well.
 
+== Running service with persistence enabled
+
+By default, Kalix services are configured to run with disabled persistence. This means that the Kalix Runtime will use an in-memory database to store the state of your service. This is useful for local development since it allows you to quickly start and stop your service without having to worry about cleaning up the database.
+
+However, if you want to run your service with persistence enabled, you can do so by changing the `docker-compose` file as below.
+
+[source, dockerfile, indent=0]
+----
+include::example$java-spring-doc-snippets/docker-compose.yml[tag=persistence-mode]
+----
+<1> Maps local directory to the Kalix Runtime database directory `/var/kalix`.
+<2> Sets `PERSISTENCE_ENABLED` env to `true`.
+
 == Running multiple services locally
 
 A typical Kalix application is composed of one or more services deployed to the same Kalix project. When deployed under the same Kalix project, two different services can make xref:component-and-service-calls.adoc[calls to each other] or xref:service-to-service.adoc[subscribe to each other's event streams] by simply using their logical names.

samples/java-protobuf-customer-registry-kafka-quickstart/docker-compose.yml

@@ -3,11 +3,15 @@ services:
   kalix-runtime:
     image: gcr.io/kalix-public/kalix-runtime:1.1.27
     container_name: java-protobuf-customer-registry-kafka-quickstart
+    # uncomment volumes when persistence is enabled
+#    volumes:
+#      - ./target/kalix:/var/kalix
     ports:
       - "9000:9000"
     extra_hosts:
       - "host.docker.internal:host-gateway"
     environment:
+      PERSISTENCE_ENABLED: "false" #when true uncomment volumes above
       JAVA_TOOL_OPTIONS: >
         -Dkalix.proxy.eventing.support=kafka
       USER_FUNCTION_HOST: ${USER_FUNCTION_HOST:-host.docker.internal}

samples/java-spring-doc-snippets/docker-compose.yml

@@ -1,17 +1,24 @@
-
+# tag::persistence-mode[]
 version: "3"
 services:
   kalix-runtime:
     image: gcr.io/kalix-public/kalix-runtime:1.1.27
+    # uncomment volumes when persistence is enabled
+    volumes: # <1>
+      - ./target/kalix:/var/kalix
     ports:
       - "9000:9000"
     extra_hosts:
       - "host.docker.internal:host-gateway"
     environment:
+      PERSISTENCE_ENABLED: "true" # <2>
+      # end::persistence-mode[]
       JAVA_TOOL_OPTIONS: >
         -Dkalix.proxy.eventing.support=google-pubsub-emulator
+      # tag::persistence-mode[]
       USER_FUNCTION_HOST: ${USER_FUNCTION_HOST:-host.docker.internal}
       USER_FUNCTION_PORT: ${USER_FUNCTION_PORT:-8080}
+      # end::persistence-mode[]
       PUBSUB_EMULATOR_HOST: gcloud-pubsub-emulator
       # Comment to enable ACL check in dev-mode (see https://docs.kalix.io/services/using-acls.html#_local_development_with_acls)
       ACL_ENABLED: "false"

samples/scala-protobuf-doc-snippets/docker-compose.yml

@@ -1,19 +1,24 @@
+# tag::persistence-mode[]
 version: "3"
 services:
   kalix-runtime:
     image: gcr.io/kalix-public/kalix-runtime:1.1.27
-    container_name: scala-protobuf-doc-snippets
-    depends_on:
-      - gcloud-pubsub-emulator
+    # uncomment volumes when persistence is enabled
+    volumes: # <1>
+      - ./target/kalix:/var/kalix
     ports:
       - "9000:9000"
     extra_hosts:
       - "host.docker.internal:host-gateway"
     environment:
+      PERSISTENCE_ENABLED: "true" # <2>
+      # end::persistence-mode[]
       JAVA_TOOL_OPTIONS: >
         -Dkalix.proxy.eventing.support=google-pubsub-emulator
+      # tag::persistence-mode[]
       USER_FUNCTION_HOST: ${USER_FUNCTION_HOST:-host.docker.internal}
       USER_FUNCTION_PORT: ${USER_FUNCTION_PORT:-8080}
+      # end::persistence-mode[]
       # Comment to enable ACL check in dev-mode (see https://docs.kalix.io/services/using-acls.html#_local_development_with_acls)
       ACL_ENABLED: "false"
       # Uncomment to enable advanced view features locally (note: disabled in deployed services by default)