docs: documenting persistent dev mode (#1918)

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

@@ -121,9 +121,22 @@ grpcurl ^
 - The address of the Kalix Runtime (using `plaintext` instead of TLS)
 - The RPC procedure name which is deduced from the protobuf definition of the component you're calling.
 
-== Shut down the service
+== Shutting 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 locally with persistence disabled. This means the Kalix Runtime will use an in-memory datastore for the state of your services. This is useful for local development since it allows you to quickly start and stop your service without having to worry about cleaning the database.
+
+However, if you want to run your service with persistence enabled to keep the data when restarting, you may update 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` environment variable to `true`.
 
 == Running multiple services locally
 

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

@@ -83,10 +83,23 @@ curl -XGET localhost:9000/customer/one
 ----
 --
 
-== Shut down the service
+== Shutting 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.
 
+== Running service with persistence enabled
+
+By default, Kalix services are configured to run locally with persistence disabled. This means the Kalix Runtime will use an in-memory datastore for the state of your services. This is useful for local development since it allows you to quickly start and stop your service without having to worry about cleaning the database.
+
+However, if you want to run your service with persistence enabled to keep the data when restarting, you may update 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` environment variable 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)

styles/Vocab/Base/accept.txt

@@ -35,6 +35,7 @@ config
 configs
 CRDTs
 Ctrl
+datastore
 deserialize
 deserializing
 deserialization