Update docs

Author: michael-bouvy

Dockerfile

@@ -30,6 +30,8 @@ RUN php -d memory_limit=2G bin/magento setup:static-content:deploy \
 
 RUN mv app/etc/env.php.bak app/etc/env.php
 
+RUN rm -rf var/*
+
 COPY docs/docker/php/custom.ini /usr/local/etc/php/conf.d/custom.ini
 COPY docs/docker/php/www.conf /usr/local/etc/php-fpm.d/www.conf
 

docs/.vitepress/config.mts

@@ -15,13 +15,15 @@ const config = defineConfig({
       { text: 'Introduction', link: '/guide/introduction' },
       { text: 'Requirements', link: '/guide/requirements' },
       {
-        text: 'Preparation',
+        text: '📚 Preparation',
+        collapsed: false,
         items: [
           { text: 'Environment variables', link: '/guide/preparation/environment-variables' },
         ]
       },
       {
-        text: 'Build',
+        text: '⚙️ Build',
+        collapsed: false,
         items: [
           { text: 'Introduction', link: '/guide/build/introduction' },
           { text: 'Docker image', link: '/guide/build/docker' },
@@ -31,11 +33,14 @@ const config = defineConfig({
         ]
       },
       {
-        text: 'Deployment',
+        text: '🚀 Deployment',
+        collapsed: false,
         items: [
           { text: 'Introduction', link: '/guide/deployment/introduction' },
           { text: 'External services', link: '/guide/deployment/external-services' },
           { text: 'Architecture', link: '/guide/deployment/architecture' },
+          { text: 'Resources and scaling', link: '/guide/deployment/resources-scaling' },
+          { text: 'Helm chart', link: '/guide/deployment/helm-chart' },
         ]
       }
     ],

docs/docker/nginx/vhost.nginx

@@ -23,7 +23,7 @@ log_format nginxlog_json escape=json
 
 server {
     listen 80;
-    server_name <your-magento-hostname>;
+
     set $MAGE_ROOT /app;
     set $MAGE_DEBUG_SHOW_ARGS 0;
 
@@ -43,50 +43,12 @@ server {
 
     # PHP entry point for setup application
     location ~* ^/setup($|/) {
-        root $MAGE_ROOT;
-        location ~ ^/setup/index.php {
-            fastcgi_pass   fastcgi_backend;
-
-            fastcgi_param  PHP_FLAG  "session.auto_start=off \n suhosin.session.cryptua=off";
-            fastcgi_param  PHP_VALUE "memory_limit=756M \n max_execution_time=600";
-            fastcgi_read_timeout 600s;
-            fastcgi_connect_timeout 600s;
-
-            fastcgi_index  index.php;
-            fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
-            include        fastcgi_params;
-        }
-
-        location ~ ^/setup/(?!pub/). {
-            deny all;
-        }
-
-        location ~ ^/setup/pub/ {
-            add_header X-Frame-Options "SAMEORIGIN";
-        }
+        deny all;
     }
 
     # PHP entry point for update application
     location ~* ^/update($|/) {
-        root $MAGE_ROOT;
-
-        location ~ ^/update/index.php {
-            fastcgi_split_path_info ^(/update/index.php)(/.+)$;
-            fastcgi_pass   fastcgi_backend;
-            fastcgi_index  index.php;
-            fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
-            fastcgi_param  PATH_INFO        $fastcgi_path_info;
-            include        fastcgi_params;
-        }
-
-        # Deny everything but index.php
-        location ~ ^/update/(?!pub/). {
-            deny all;
-        }
-
-        location ~ ^/update/pub/ {
-            add_header X-Frame-Options "SAMEORIGIN";
-        }
+        deny all;
     }
 
     location / {
@@ -179,7 +141,6 @@ server {
 
     # PHP entry point for main application
     location ~ ^/(index|get|static|errors/report|errors/404|errors/503|health_check)\.php$ {
-        try_files $uri =404;
         fastcgi_pass   fastcgi_backend;
         fastcgi_buffers 16 16k;
         fastcgi_buffer_size 32k;

docs/docker/php/custom.ini

@@ -1,5 +1,5 @@
 date.timezone = Etc/UTC
-# Recommended value by Magento / Adobe Commerce
+; Recommended value by Magento / Adobe Commerce
 memory_limit = 756M
 log_errors = On
 display_errors = Off
@@ -14,13 +14,13 @@ opcache.interned_strings_buffer = 32
 opcache.max_accelerated_files = 130987
 opcache.enable_file_override = 1
 
-# When set to 0, you'll need to restart the PHP process to apply changes to PHP files, which should never happen in production
+; When set to 0, you'll need to restart the PHP process to apply changes to PHP files, which should never happen in production
 opcache.consistency_checks = 0
 opcache.validate_timestamps = 0
 
 realpath_cache_size = 10M
 realpath_cache_ttl = 7200
 
-# Increase the maximum file upload size ; those should be set according to your needs (i.e. for image uploads from admin)
+; Increase the maximum file upload size ; those should be set according to your needs (i.e. for image uploads from admin)
 upload_max_filesize = 20M
 post_max_size = 20M

docs/docker/php/www.conf

@@ -5,11 +5,13 @@ group = www-data
 listen = 127.0.0.1:9000
 
 pm = static
-pm.max_children = 10 # Or use an environment variable, such as ${PHP_FPM_MAX_CHILDREN}
+; Or use an environment variable, such as ${PHP_FPM_MAX_CHILDREN}
+pm.max_children = 10
 pm.status_path = /status
-# Useful to avoid memory leaks ; processes will be restarted after handling 10 requests
+; Useful to avoid memory leaks ; processes will be restarted after handling 10 requests
 pm.max_requests = 10
 
-# Useful to send logs from all workers to the main process, which will then send them to stdout
+; Useful to send logs from all workers to the main process, which will then send them to stdout
+; Note that those are usually already defined in /usr/local/etc/php-fpm.d/docker.conf shipped with PHP FPM docker image
 catch_workers_output = yes
 decorate_workers_output = no

docs/guide/build/docker.md

@@ -202,7 +202,7 @@ bin/magento app:config:dump scopes themes i18n
 ```
 
 > [!IMPORTANT]
-> This command should be run outside of the Docker image, as it requires a database connection.
+> This command should be run outside the Docker image, as it requires a database connection.
 > The resulting `config.php` should be added to the VCS, so it's available when building the Docker image.
 
 > [!NOTE]
@@ -238,7 +238,11 @@ Once the static content is deployed, we can move back the `env.php` file:
 RUN mv app/etc/env.php.bak app/etc/env.php
 ```
 
-## PHP configuration
+We can now do some cleanup:
+
+```dockerfile
+RUN rm -rf var/*
+```
 
 Although the PHP configuration is generally good enough for most cases, you may want to tweak it to your needs.
 
@@ -284,7 +288,7 @@ COPY www.conf /usr/local/etc/php-fpm.d/www.conf
 
 ## nginx
 
-Now that we have our PHP-FPM image ready, we need to add an nginx server to serve our Magento / Adobe Commerce project, communicating with PHP-FPM using fastcgi.
+Now that we have our PHP-FPM image ready, we need to add a nginx server to serve our Magento / Adobe Commerce project, communicating with PHP-FPM using fastcgi.
 
 To serve static assets in an efficient way, we'll also copy the `pub/static` directory to the nginx image.
 
@@ -305,7 +309,9 @@ upstream fastcgi_backend {
 
 server {
    listen 80;
-   server_name <your-magento-hostname>;
+    
+   # server_name directive is not mandatory, as we're using the default server block
+
    set $MAGE_ROOT /app;
    set $MAGE_DEBUG_SHOW_ARGS 0;
 
@@ -320,33 +326,83 @@ Additionnaly, you may change the following in the resulting `vhost.conf` file:
 
 ::: code-group
 
-```nginx [At root level of vhost.conf]
-log_format nginxlog_json escape=json 
-    '{ "timestamp": "$time_iso8601", '
-    '"remote_addr": "$remote_addr", '
-    '"body_bytes_sent": $body_bytes_sent, '
-    '"request_time": $request_time, '
-    '"response_status": $status, '
-    '"request": "$request", '
-    '"request_method": "$request_method", '
-    '"host": "$host",'
-    '"remote_user": "$remote_user",'
-    '"request_uri": "$request_uri",'
-    '"query_string": "$query_string",'
-    '"upstream_addr": "$upstream_addr",'
-    '"http_x_forwarded_for": "$http_x_forwarded_for",'
-    '"http_x_real_ip": "$http_x_real_ip",'
-    '"http_referrer": "$http_referer", '
-    '"http_user_agent": "$http_user_agent", '
-    '"http_version": "$server_protocol" }';
+```nginx [vhost.conf]
+log_format nginxlog_json escape=json # [!code ++]
+    '{ "timestamp": "$time_iso8601", ' # [!code ++]
+    '"remote_addr": "$remote_addr", ' # [!code ++]
+    '"body_bytes_sent": $body_bytes_sent, ' # [!code ++]
+    '"request_time": $request_time, ' # [!code ++]
+    '"response_status": $status, ' # [!code ++]
+    '"request": "$request", ' # [!code ++]
+    '"request_method": "$request_method", ' # [!code ++]
+    '"host": "$host",' # [!code ++]
+    '"remote_user": "$remote_user",' # [!code ++]
+    '"request_uri": "$request_uri",' # [!code ++]
+    '"query_string": "$query_string",' # [!code ++]
+    '"upstream_addr": "$upstream_addr",' # [!code ++]
+    '"http_x_forwarded_for": "$http_x_forwarded_for",' # [!code ++]
+    '"http_x_real_ip": "$http_x_real_ip",' # [!code ++]
+    '"http_referrer": "$http_referer", ' # [!code ++]
+    '"http_user_agent": "$http_user_agent", ' # [!code ++]
+    '"http_version": "$server_protocol" }'; # [!code ++]
+
+server {
+    ...
+    access_log /dev/stdout nginxlog_json; # [!code ++]
+    ...
+}
 ```
 
-```nginx [Within the server block]
-access_log /dev/stdout nginxlog_json;
+:::
+
+* Remove unnecessary blocks:
+  * `location ~* ^/setup($|/) { ... }`
+  * `location ~* ^/update($|/) { ... }`
+
+* Add a health check endpoint, to be able to monitor the nginx server:
+
+::: code-group
+    
+```nginx [vhost.conf]
+server {
+    ...
+
+    location /nginx-health { # [!code ++]
+        add_header Content-Type text/plain; # [!code ++]
+        return 200 'OK'; # [!code ++]
+    } # [!code ++]
+}
 ```
 
 :::
 
+* Increase the buffers size in the main entry point:
+
+::: code-group
+
+```nginx [vhost.conf]
+    # PHP entry point for main application
+    location ~ ^/(index|get|static|errors/report|errors/404|errors/503|health_check)\.php$ {
+        fastcgi_buffers 16 16k; # [!code --]
+        fastcgi_buffer_size 32k; # [!code --]
+        fastcgi_buffers 16 32k; # [!code ++]
+        fastcgi_buffer_size 64k; # [!code ++]
+        fastcgi_busy_buffers_size 64k; # [!code ++]
+        proxy_buffer_size 128k; # [!code ++]
+        proxy_buffers 4 256k; # [!code ++]
+        proxy_busy_buffers_size 256k; # [!code ++]
+
+        ...
+    }
+```
+
+:::
+
+> [!INFO]
+> The complete `vhost.conf` file can be found [here](https://github.com/ClickAndMortar/magento-kubernetes/blob/main/docs/docker/nginx/vhost.nginx).
+
+---
+
 The resulting `Dockefile` should look like this:
 
 ```dockerfile
@@ -397,7 +453,8 @@ Then push the images to your container registry, using `docker push`.
 > [!TIP]
 > When cross-building images for different architectures, you may want to use the `--platform` flag to specify the target architecture, such as `linux/amd64`, `linux/arm64`, etc.
 
-The complete `Dockerfile` can be found [here](https://github.com/ClickAndMortar/magento-kubernetes/blob/main/Dockerfile).
+> [!INFO]
+> The complete `Dockerfile` can be found [here](https://github.com/ClickAndMortar/magento-kubernetes/blob/main/Dockerfile).
 
 ## Tagging strategy