Update docs

.gitignore

@@ -5,3 +5,5 @@ magento
 # Vitepress
 docs/.vitepress/dist
 docs/.vitepress/cache
+
+node_modules

docs/.vitepress/config.mts

@@ -15,16 +15,27 @@ const config = defineConfig({
       { text: 'Introduction', link: '/guide/introduction' },
       { text: 'Requirements', link: '/guide/requirements' },
       {
-        text: 'Configuration',
+        text: 'Preparation',
         items: [
-          { text: 'Environment variables', link: '/guide/configuration/environment-variables' },
+          { text: 'Environment variables', link: '/guide/preparation/environment-variables' },
         ]
       },
       {
         text: 'Build',
         items: [
           { text: 'Introduction', link: '/guide/build/introduction' },
-          { text: 'Docker', link: '/guide/build/docker' },
+          { text: 'Docker image', link: '/guide/build/docker' },
+          { text: 'New Relic', link: '/guide/build/newrelic' },
+          { text: 'Optimization', link: '/guide/build/optimization' },
+          { text: 'Security', link: '/guide/build/security' },
+        ]
+      },
+      {
+        text: 'Deployment',
+        items: [
+          { text: 'Introduction', link: '/guide/deployment/introduction' },
+          { text: 'External services', link: '/guide/deployment/external-services' },
+          { text: 'Architecture', link: '/guide/deployment/architecture' },
         ]
       }
     ],
@@ -35,6 +46,9 @@ const config = defineConfig({
     footer: {
       message: 'Released under the MIT License.<br/> This project is not affiliated with, endorsed by, or sponsored by Adobe Inc. "Magento" and "Adobe Commerce" are trademarks of Adobe Inc.<br/> All trademarks and registered trademarks are the property of their respective owners.',
       copyright: 'Copyright &copy; 2024-present <a href="https://www.clickandmortar.fr">Click &amp; Mortar</a>'
+    },
+    search: {
+      provider: 'local',
     }
   },
   head: [['link', { rel: 'icon', href: '/magento-kubernetes/images/logo-transp.png' }]],

docs/.vitepress/theme/style.css

@@ -137,3 +137,7 @@
   --docsearch-primary-color: var(--vp-c-brand-1) !important;
 }
 
+.mermaid svg {
+    display: block;
+    margin: 0 auto;
+}

docs/docker/php/custom.ini

@@ -1,5 +1,6 @@
 date.timezone = Etc/UTC
-memory_limit = 756M # Recommended value by Magento / Adobe Commerce
+# Recommended value by Magento / Adobe Commerce
+memory_limit = 756M
 log_errors = On
 display_errors = Off
 display_startup_errors = Off

docs/guide/build/docker.md

@@ -291,7 +291,8 @@ To serve static assets in an efficient way, we'll also copy the `pub/static` dir
 > [!INFO]
 > The same way we did for the PHP image, we'll be using the [official nginx image](https://hub.docker.com/_/nginx) as a base image.<br/>
 > We recommend using the `alpine` version, which is lightweight and secure.<br/>
-> As with PHP image, you may want to use a specific version of the image to avoid any surprises. 
+> As with PHP image, you may want to use a specific version of the image to avoid any surprises.<br/>
+> Note that Adobe recommends using version 1.24 of nginx for Magento 2.4.7.
 
 A sample `nginx.conf.sample` file is provided in the Magento / Adobe Commerce repository, which you can use as a base for your configuration.
 

docs/guide/build/newrelic.md

@@ -0,0 +1,60 @@
+---
+title: New Relic
+layout: doc
+---
+
+# New Relic
+
+As detailed in the [official New Relic documentation](https://docs.newrelic.com/docs/apm/agents/php-agent/installation/php-agent-installation-overview/), the PHP agent consists of two components:
+
+* A PHP extension, which collects data from your application
+* A local proxy daemon, which transmits the data to New Relic
+
+In this section, we'll cover how to install the New Relic PHP extension, which will forward data to the New Relic daemon.
+
+Installation of the New Relic daemon in your Kubernetes cluster will be covered in a separate section, under Deployment part.
+
+## Installation
+
+The PHP extension can be downloaded from https://download.newrelic.com/php_agent/release/. The latest version at the time of writing is `10.21.0.11`.
+
+To install the New Relic PHP extension, follow these steps:
+
+* Create a `newrelic.ini` file:
+
+::: code-group
+
+```ini [newrelic.ini]
+extension = "newrelic.so"
+
+[newrelic]
+newrelic.license = "${NEWRELIC_LICENSE_KEY}"
+newrelic.appname = "${NEWRELIC_APP_NAME}"
+newrelic.daemon.address = "${NEWRELIC_DAEMON_HOST}:${NEWRELIC_DAEMON_PORT}"
+newrelic.daemon.dont_launch = 3
+```
+
+:::
+
+> [!NOTE]
+> To make the configuration portable, we recommend using environment variables for the `NEWRELIC_LICENSE_KEY`, `NEWRELIC_APP_NAME`, `NEWRELIC_DAEMON_HOST`, and `NEWRELIC_DAEMON_PORT` values.
+> Therefore, those values should be set as environment variables where the PHP process is running (discussed in the Deployment section).
+
+* Download the PHP extension and copy the configuration file in your Docker image:
+
+::: code-group
+
+```dockerfile [Dockerfile]
+FROM php:<tag>
+
+# Install New Relic PHP extension
+RUN curl -sSL https://download.newrelic.com/php_agent/release/newrelic-php5-10.21.0.11-linux.tar.gz -o /tmp/newrelic.tgz \
+    && tar -xzf /tmp/newrelic.tgz -C /tmp \
+    && cp newrelic-php5-10.21.0.11-linux/agent/aarch64/newrelic-20230831.so $(php -r 'echo ini_get("extension_dir");')/newrelic.so \
+    && rm -rf /tmp/newrelic*
+
+# Copy the New Relic configuration file
+COPY newrelic.ini /usr/local/etc/php/conf.d/newrelic.ini
+```
+
+:::

docs/guide/build/optimization.md

@@ -0,0 +1,5 @@
+---
+title: Optimization
+---
+
+# Optimization

docs/guide/build/security.md

@@ -0,0 +1,5 @@
+---
+title: Security
+---
+
+# Security

docs/guide/deployment/architecture.md

@@ -0,0 +1,111 @@
+---
+title: Architecture
+---
+
+# Architecture
+
+Magento / Adobe Commerce consists of three main components that work together:
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+graph TD
+    A["`**Web servers**
+    nginx / PHP-FPM`"]
+    B["`**Consumers**
+    PHP CLI`"]
+    C["`**Crons**
+    PHP CLI`"]
+```
+
+We will be using the following Kubernetes main resources:
+
+* **Web servers**: `Deployments`, `HorizontalPodAutoscalers` and `Services`
+* **Consumers**: `Deployments` with 1 replica per consumer
+* **Crons**: `CronJobs`
+
+Additionally, we will also be using the following resources:
+
+* **ConfigMaps**: to store environment variables
+* **Secrets**: to store sensitive environment variables
+* **PersisventVolumes** / **PersistentVolumeClaims**: to store persistent data (media, etc.) and share it between pods
+
+## Components
+
+### Web servers
+
+Web servers are the main entry point for the application. They are responsible for serving the web pages to the users.
+
+The `Pods` will have two containers:
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+graph TD
+    subgraph "`**Pod**`"
+        A["`**Container**
+        nginx`"]
+        B["`**Container**
+        PHP-FPM`"]
+        A -- TCP/9000 --> B
+    end
+```
+
+> [!IMPORTANT]
+> `Deployments` processing web traffic should always have at least 2 replicas, to ensure service availability (i.e. during upgrades) but also to make sure that the application is ready to scale horizontally if needed.
+> In a production deployment, this will be handled using a `HorizontalPodAutoscaler`.
+
+### Consumers
+
+Consumers are responsible for processing messages from the message queue (RabbitMQ or MySQL). They are long-running processes that will be running in the background.
+
+One `Deployment` needs to be created for each consumer, each containing a single PHP CLI container.
+
+> [!IMPORTANT]
+> At the time of writing, Magento / Adobe Commerce does not handle UNIX signals properly, which means that the containers will not be able to handle graceful shutdowns.
+> Therefore, the `Pods` will be terminated immediately, without giving the application time to finish processing the current message.
+
+TODO: fork handling (standalone process)?
+
+### Crons
+
+Crons are responsible for running scheduled tasks. They are short-lived processes that will be running at specific intervals.
+
+One `CronJob` will be used to run the crons, with a single PHP CLI container.
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}} }%%
+graph TD
+    subgraph CronJob["`**CronJob**
+    Schedule: every minute`"]
+    end
+    subgraph Job["`**Job**`"]
+    end
+    subgraph Job2["`**Job**`"]
+    end
+    subgraph Pod["`**Pod**`"]
+        A["`**Container**
+        PHP CLI`"]
+    end
+    subgraph Pod2["`**Pod**`"]
+        B["`**Container**
+        PHP CLI`"]
+    end
+    CronJob -- "`Creates
+    _(Minute 1)_`" --> Job
+    CronJob -. "`Creates
+    _(Minute 2)_`" .-> Job2
+    Job -- Creates --> Pod
+    Job2 -. Creates .-> Pod2
+    style Job2 stroke-dasharray: 5 5
+    style Pod2 stroke-dasharray: 5 5
+    style B stroke-dasharray: 5 5
+```
+
+The `CronJob` will create a new `Job` every minute, which will create a new `Pod` with a PHP CLI container.
+
+As we need to allow concurrent executions of the same cron, to avoid leaving jobs unprocessed (i.e. during reindexing), new `Jobs` and their `Pods` might spin up before the previous ones have finished.
+
+> [!WARNING]
+> Allowing concurrent executions of the same cron might lead to have many `Pods` running at the same time, which might lead to performance issues.
+> This should be monitored and adjusted as needed.
+
+TODO: cron groups

docs/guide/deployment/external-services.md

@@ -0,0 +1,35 @@
+---
+title: External services
+---
+
+# External services
+
+Magento / Adobe Commerce relies on several external services to function properly.
+
+The following versions are currently supported by Magento / Adobe Commerce 2.4.7:
+
+| Category   | Service                   | Version | Type       | Required             |
+|------------|---------------------------|---------|------------|----------------------|
+| Database   | MySQL                     | 8.0     | On premise | :heavy_check_mark: * |
+| Database   | MariaDB                   | 10.6    | On premise | :heavy_check_mark: * |
+| Database   | AWS Aurora MySQL          | 8.0     | Managed    | :heavy_check_mark: * |
+| Data cache | Redis                     | 7.0     | On premise | :heavy_check_mark: * |
+| Data cache | AWS Elasticache for Redis | 7.0     | Managed    | :heavy_check_mark: * |
+| Page cache | Varnish                   | 7.5     | On premise |                      |
+| Search     | Elasticsearch             | 8.11    | On premise | :heavy_check_mark: * |
+| Search     | OpenSearch                | 2.12    | On premise | :heavy_check_mark: * |
+| Search     | AWS OpenSearch            | 2.11    | Managed    | :heavy_check_mark: * |
+| Message    | RabbitMQ                  | 3.13    | On premise |                      |
+| Message    | AWS MQ                    | 3.11.20 | Managed    |                      |
+
+> _\* : one database, one data cache, and one search service are required_
+
+An up-to-date list of supported versions can be found in the [official documentation](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/system-requirements), under `Commerce on-premises` tab.
+
+> [!INFO]
+> Whenever possible, we recommend using managed services for databases, caches, and message queues. Managed services are easier to maintain and scale, and they often come with built-in monitoring and backup solutions.
+> Although Adobe only officially supports AWS managed services, **you can use other cloud providers as well**, as long as the service versions are compatible with Magento / Adobe Commerce.
+
+## Database
+
+TODO

docs/guide/deployment/introduction.md

@@ -0,0 +1,14 @@
+---
+title: Introduction
+---
+
+# Introduction
+
+In order to deploy our freshly built Docker image to Kubernetes, several options are available:
+
+* **Manual deployment**: You can manually deploy your Docker image to Kubernetes using `kubectl` commands and YAML manifests
+* **Helm chart**: You can use a [Helm](https://helm.sh/) chart to deploy your Docker image to Kubernetes
+* **Kustomize**: You can use [Kustomize](https://kustomize.io/) to deploy your Docker image to Kubernetes
+* **GitOps**: You can use GitOps ([ArgoCD](https://argo-cd.readthedocs.io/en/stable/), [Flux](https://fluxcd.io/)) to deploy your Docker image to Kubernetes
+
+In this guide, we'll be using the **Helm chart** option to deploy our Docker image to Kubernetes, along with everything else required to run Magento / Adobe Commerce.

docs/guide/configuration/environment-variables.md → docs/guide/preparation/environment-variables.md

@@ -28,6 +28,13 @@ The slash character of config paths should be replaced with double underscores:
 > [!IMPORTANT]
 > Magento / Adobe Commerce caches the configuration values. If you change the value of an environment variable, you need to clear the cache to see the changes.
 
+In a regular Magento / Adobe Commerce deployment, you might need to define the following environment variables for your config:
+
+| Variable name                | Description                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|
+| `MAGENTO_DATABASE_HOST`      | Database host                                                               |
+
+
 ## `env.php`
 
 Magento / Adobe Commerce does not offer a mechanism similar to the one above for values of `env.php`.
@@ -73,7 +80,3 @@ You may also define defaults for those environment variables in your `env.php` f
     ],
     ...
 ```
-
-## Conclusion
-
-At this point, your Magento / Adobe Commerce project should be able to read configuration values from environment variables, and you should be able to define environment-specific configuration values in your environment.

docs/index.md

@@ -15,10 +15,13 @@ hero:
       link: /guide/introduction
 
 features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Scalability and Flexibility
+    icon: ↕️
+    details: Effortlessly scale your Magento store to handle increased traffic with Kubernetes' auto-scaling capabilities
+  - title: Automated Rollouts and Rollbacks
+    icon: 🔄
+    details: Ensure seamless updates and quick recoveries with Kubernetes' automated deployment strategies
+  - title: High Availability and Fault Tolerance
+    icon: 🛡️
+    details: Achieve maximum uptime and reliability with Kubernetes' self-healing and load-balancing features
 ---