Add multistage Dockerfile documentation

Author: febus982

README.md

@@ -82,3 +82,20 @@ Locally:
 * `make generate-proto`: Generates grpcio python stubs from `.proto` files in `grpc_app/proto` directory
 * `make check`: Run tests, code style and lint checks
 * `make fix`: Run tests, code style and lint checks with automatic fixes (where possible)
+
+## Multistage dockerfile configuration
+
+Python docker image tend to become large after installing the application requirements
+(the slim base is ~150 MB uncompressed), therefore it's important to spend efforts
+to minimise the image size, even if it produces a slightly more complex multistage
+Dockerfile.
+
+The following setup makes sure the production image will keep to a minimal size ("only" 390MB):
+ * 150MB base image
+ * 165MB python installed dependencies
+ * 73MB poetry + updated pip
+
+Using the following pipeline the "test" image is instead ~850MB, more than 400MB that would
+end up as a cost in traffic on each image pull.
+
+![](docker-container.png)

docker-container.png

@@ -0,0 +1,76 @@
+@startuml
+usecase base [
+    =Base
+    ----
+    ""Contains system runtime ""
+    ""libraries necessary to run""
+    ""all the applications""
+    ""(e.g. libmysql)""
+]
+usecase base_builder [
+    =Base Builder
+    ----
+    ""Contains system libraries""
+    ""necessary to build python""
+    ""dependencies""
+    ""(e.g. gcc, library headers)""
+]
+usecase test [
+    =Test
+    ----
+    ""Fat image containing everything""
+    ""necessary to run and test""
+    ""all the applications""
+]
+usecase base_app [
+    =Base app
+    ----
+    ""Copies shared application logic""
+    ""independent from the used framework""
+    ""(domains, storage, etc.)""
+]
+
+rectangle HTTP {
+    usecase http_builder [
+        =Http builder
+        ----
+        ""Builds HTTP dependencies""
+    ]
+    usecase http_app [
+        =Http app
+        ----
+        ""Copies HTTP framework""
+        ""shared logic""
+        ""and dependencies""
+        "" to run the application""
+    ]
+}
+rectangle GRPC {
+    usecase grpc_builder [
+        =GRPC builder
+        ----
+        ""Builds GRPC dependencies""
+    ]
+    usecase grpc_app [
+        =GRPC app
+        ----
+        ""Copies HTTP framework""
+        ""shared logic""
+        ""and dependencies""
+        "" to run the application""
+    ]
+}
+
+base ==r=> base_builder
+base ==l=> base_app
+
+base_builder ===> http_builder
+http_builder ===> http_app
+base_app ===> http_app
+
+base_builder ===> grpc_builder
+grpc_builder ===> grpc_app
+base_app ===> grpc_app
+
+base_builder ==r=> test
+@enduml