add info about the new profile for docker run (#115)

Author: nicoloboschi

installation/docker.md

@@ -33,8 +33,10 @@ This command starts a docker container using the same version of the CLI.
 
 The container by default runs all the LangStream components, a Kafka Broker, and an S3 service (using [Minio](https://min.io/docs/minio/kubernetes/upstream/index.html)).
 
-The docker container exposes the Control Plane on the default port (8090) and the API Gateway on the default port (8091),
-so you can run most of the CLI commands against the local container, especially the commands to interact with the API Gateway.
+The docker container exposes the Control Plane on the default port (`8090`) and the API Gateway on the default port (`8091`),
+so you can run most of the CLI commands against the local container, especially the commands to interact with the API Gateway. See this [section](#connect-to-the-docker-application) to learn more.
+
+Note that one of the two port is not available, the command will fail. Parallel executions of local run is not supported. 
 
 When you kill the application with Ctrl-C, the environment is automatically disposed of.
 If you need to persist your topics or the S3 environment, then you have to build your own instance.yaml file and pass it using the "-i" flag.
@@ -51,11 +53,11 @@ By default the docker container runs all the LangStream components, a Kafka Brok
 
 You can use the following flags to select the services to run:
 
-* --start-broker true|false: starts the Kafka broker (default is `true`)
-* --start-s3 true|false: starts the S3 service (default is `true`)
-* --start-webservices true|false: starts the LangStream HTTP components (control plane and API gateway) (default is `true`)
-* --start-database true|false: starts an embedded vector JDBC compliant database (HerdDB) (default is `true`)
-* --start-ui true|false: starts and open a UI application that helps you to test the application
+* `--start-broker`: starts the Kafka broker (default is `true`)
+* `--start-s3`: starts the S3 service (default is `true`)
+* `--start-webservices`: starts the LangStream HTTP components (control plane and API gateway) (default is `true`)
+* `--start-database`: starts an embedded vector JDBC compliant database (HerdDB) (default is `true`)
+* `--start-ui`: starts and open a UI application that helps you to test the application (default is `true`)
 
 For example, if you are using an external Apache Kafka or Pulsar broke, you don't need to start Kafka in the container and you can save local resources by not running the service.
 
@@ -72,14 +74,14 @@ the id would be the id of a Statefulset.
 
 When you run your application in "docker run" mode, the container runs a simplified environment that doesn't need Kubernetes, but this comes with a few simplifications to the execution runtime.
 
-In production mode on Kubernetes, the LangStream planner builds an execution plan from your pipeline files, and then it submits the execution plan to the Kubernetes cluster in the form of Statefulsets. Each Statefulset is responsible for running a single agent. You can configure the number of replicas for each agent in the "resources" section of the pipeline.yaml file.
+In production mode on Kubernetes, the LangStream planner builds an execution plan from your pipeline files, and then it submits the execution plan to the Kubernetes cluster in the form of Statefulsets. Each Statefulset is responsible for running a single executor (one or many agents). You can configure the number of replicas for each agent in the `resources` section of the pipeline.yaml file. In docker mode, the resources configuration is ignored.
 
 In docker mode there is only one Java process that runs all the agents, and for each agent it starts only one execution flow, like having a Statefulset with only one replica.
-The resources (JVM and CPU) are shared between all the agents, so if you have a lot of agents in your application you may need to increase the resources of the docker container (see "Tuning the docker container" below).
+The resources (memory and CPU) are shared between all the agents, so if you have a lot of agents in your application you may need to increase the resources of the docker container (see [Tuning the docker container](#tuning-the-docker-container) below).
 
-The initialisation of the assets is always performed independently from the agents that are running, for all the assets declared in the application. This is because the assets are shared between all the agents, even if they are declared in some pipeline file.
+The initialisation of the assets is always performed independently from the agents that are running, for all the assets declared in the application. The deletion of the assets is not performed in this mode.
 
-You cannot select which logs to display, as all the agents share the same output (but you can still run one agent at a time). The "langstream apps logs" command is not available in this mode.
+You cannot select which logs to display, as all the agents share the same output (but you can still run one agent at a time). The `langstream apps logs` command is not available in this mode.
 
 
 ### Tuning the docker container
@@ -100,3 +102,20 @@ The following flags are available:
 If you have built [the CLI locally from the sources](../installation/build-and-install-source.md) the docker image defaults to the local docker image
 
 You can also override the command used to launch the container, the default value is `docker`, but you can pass the `--docker-command` flag to use a different binary path.
+
+
+### Connect to the docker application
+The docker container exposes the API gateway on port `8091` and the control plane on port `8090` of your local machine. 
+To connect to the docker container it's highly suggested to use a special profile named `local-docker-run`.
+This profile ensures you will always connect to the right endpoints.
+
+For example, starting the chat gateway:
+```bash
+langstream -p local-docker-run gateway chat test chat
+```
+
+or for getting the application description:
+```bash
+langstream -p local-docker-run apps get test -o yaml
+```
+