Add docs for stay open mode

content/en/localstack/configuration.md

@@ -99,6 +99,7 @@ This section covers configuration values that are specific to AWS services.
 | | `docker` (default) | Run each function invocation in a separate Docker container. |
 | | `local` (fallback) | Run Lambda functions in a temporary directory on the local machine. |
 | | `docker-reuse` | Create one Docker container per function and reuse it across invocations. |
+| `LAMBDA_STAY_OPEN_MODE` | `1` (default) | Usage of the [stay-open mode]({{< ref "lambda-executors#stay-open-mode" >}}) of Lambda containers. Only applicable if `LAMBDA_EXECUTOR=docker-reuse`. |
 | `LAMBDA_REMOTE_DOCKER` | | determines whether Lambda code is copied or mounted into containers |
 | | `true` (default) | your Lambda function definitions will be passed to the container by copying the zip file (potentially slower). It allows for remote execution, where the host and the client are not on the same machine.|
 | | `false` | your Lambda function definitions will be passed to the container by mounting a volume (potentially faster). This requires to have the Docker client and the Docker host on the same machine. Also, `HOST_TMP_FOLDER` must be set properly, and a volume mount like `${HOST_TMP_FOLDER}:/tmp/localstack` needs to be configured if you're using docker-compose. |

content/en/localstack/lambda-executors.md

@@ -45,10 +45,29 @@ A typical invocation of a dummy python lambda can take around 3 seconds from sta
 All supported lambda types can be used with this executor.
 
 
-### Docker re-use
+### Docker reuse
 
 Configuration: `LAMBDA_EXECUTOR=docker-reuse`
 
+#### Stay-open mode
+LocalStack allows to use the stay-open mode of its lambda containers.
+The containers stay open and wait for further invocations, without executing the initialization code of the lambda multiple times.
+This results in way faster execution times, especially if the lambda has long-running initialization code.
+
+The stay-open mode is the new default method when using `docker-reuse` as lambda executor, however, it has some restrictions:
+
+* Only works if LocalStack runs in a Docker container
+* Large Payloads (multiple MBs) do not work
+* Problems with error handling in some runtimes
+
+A list of failing tests with this mode can be found [in this GitHub issue](https://github.com/localstack/localstack/pull/5088).
+
+
+#### Docker-exec execution mode
+This mode is the default if LocalStack is started in host mode.
+If you experience failures using the stay-open mode (either due to the mentioned restrictions or networking problems), you can force this mode by setting `LAMBDA_STAY_OPEN_MODE=0`.
+
 This execution mode provides a balance between the speed of a local execution and the feature set and isolation of the `docker` executor.
 While the initial call, which creates the container, will take roughly the same time of `docker` executor, the subsequent invocations will only take around 1 second (start to finish, invoked using the awscli), which roughly the time an actual aws invocation using this method takes.
 The container is kept running 10 minutes after the last invocation for this lambda, then it will be destroyed (and recreated if necessary for the next invocation).
+The complete lambda process is called using `docker-exec` each time of the invocation. While the invocation is still faster than `docker` execution mode, it is not as fast as with the stay-open mode (since the lambda has to be loaded and initialized every time).