docs(TF-408): how deployment works

docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md

@@ -7,14 +7,147 @@ navigation:
 
 # Deployment - How it works?
 
+Ever wondered how Alokai transforms your codebase into a live, running application? This guide takes you behind the scenes of the deployment process, showing you exactly how your code goes from development to production.
+
+## Deployment Process Overview
+
+Ready to deploy your store? It all starts with a single command:
+
+```bash
+yarn store deploy
+```
+
+While this command is typically executed in your [continuous delivery pipeline](/guides/multistore/tooling-and-concepts/deployment/ci-cd), you can also run the deployment locally on your machine.
+
+::tip Getting Started with Deployment
+Learn how to configure your stores and run your deployment locally in the [Deployment - Configuration](/guides/multistore/tooling-and-concepts/deployment/configuration) guide. For more details about the `store deploy` command, see the [CLI reference](/guides/multistore/tooling-and-concepts/cli-reference).
+::
+
+The command performs a deployment of chosen stores. The deployment process consists of six main stages that transform your source code into running applications:
+
+1. Store Composition
+2. Build Process
+3. Docker Image Preparation
+4. Docker Image Building
+5. Image Registry Push
+6. Deployment Trigger
+
+Let's explore each stage in detail.
+
+### 1. Store Composition
+
+The journey begins with store composition. The CLI uses the [file-based inheritance](/guides/multistore/tooling-and-concepts/file-based-inheritance) rules to compose the stores by:
+- Collecting files from base applications
+- Applying overrides from parent stores, based on the file-based inheritance
+- Adding store-specific customizations
+
+Everything comes together in the temporary `.out/<store-id>` directory (which is git-ignored), ready for the next stage.
+
+::info Independent Files in `.out` Directory
+Unlike in the `apps` directory where files are shared between stores through inheritance, each store in the `.out` directory has its own independent copy of all files. Let's take a look at the following example:
+
+```bash
+apps/
+├── storefront-unified-nextjs/          # Base shared code
+    ├── tailwind.config.ts        
+    ├── ...
+└── stores/
+    ├── fashion-brand/        
+    │   ├── storefront-unified-nextjs/ 
+    │   │   ├── components/ 
+    │   │   │   ├── header.tsx 
+    │   ├── stores/
+    │   │   ├── us/
+    │   │   ├── eu/
+```
+
+The CLI copies files to their respective store directories, creating separate Next.js/Nuxt, Middleware and Playwright projects with their own complete source code for each store:
+
+```bash
+.out/
+├── us/
+│   ├── storefront-unified-nextjs/
+│   │   ├── tailwind.config.ts # a copy from base
+│   │   ├── ...
+│   │   ├── components/
+│   │   │   ├── header.tsx # a copy from fashion-brand
+└── eu/
+    ├── storefront-unified-nextjs/
+    │   ├── tailwind.config.ts # a copy from base
+    │   ├── ...
+    │   ├── components/
+    │   │   ├── header.tsx # a copy from fashion-brand
+```
+::
+
+::tip Learn more about composition
+For detailed information about how stores are composed, see the [File-based inheritance](/guides/multistore/tooling-and-concepts/file-based-inheritance) guide.
+::
+
+### 2. Build Process
+
+With the stores composed, the build phase begins. The CLI executes the `build` script defined in each application's `package.json` file to create production-ready builds.
+
+### 3. Docker Image Preparation
+
+Now comes the optimization phase. The CLI prepares standalone applications in `.out/<store-id>/<app-name>/.deploy` directories, carefully selecting only the essential files needed for production. This process significantly reduces image sizes and speeds up deployments.
+
+::tip `.deploy` Directory
+Curious about what goes into the production build? You can explore the `.deploy` directory at `.out/<store-id>/<app-name>/.deploy` after running the `store deploy` command.
+::
+
+### 4. Docker Image Building
+
+With the `.deploy` directories ready, the CLI builds Docker images for each application (Middleware and Frontend). All applications use a similar Dockerfile. A simplified version of the Dockerfile looks like this:
+
+```dockerfile
+# Use lightweight Node.js alpine as the base image
+FROM node:18-alpine
+
+# Set the working directory
+WORKDIR /var/www
+
+# Copy the optimized .deploy directory
+COPY ./.deploy/ ./
+
+# Configure the entrypoint for running the production app
+ENTRYPOINT ["node", "server.js"]
+```
+
+This simple and efficient Dockerfile structure ensures:
+- Small image sizes through the use of Alpine base image
+- Only production files are included via the `.deploy` directory
+- Proper entrypoint for running the production app
+- Maximum compatibility with CI/CD providers by using basic Docker features only (no buildx or other modern Docker features required)
+
+### 5. Image Registry Push
+
+With our optimized applications ready, the CLI:
+1. Tags images with the latest commit SHA
+2. Authenticates with the Alokai Cloud registry
+3. Pushes images to the container repository
+
+::tip Why commit SHA?
+Using commit SHAs for tagging provides unique identification of each deployment, enabling easy rollbacks and ensuring clear tracking of deployed code. Remember to always commit your changes before deploying, even for local deployments, as the SHA is used for tagging.
+::
+
+### 6. Deployment Trigger
+
+In the final stage:
+1. CLI sends request to the Alokai Console API
+2. Console orchestrates the deployment across the cloud infrastructure
+
+## Result
+
+Once the `store deploy` command completes its work, you can check the Alokai Console to monitor the deployment status and see your store transition from code to a live, running application.
 
 ::card{title="Next: Deployment - Configuration" icon="tabler:number-3-small" }
 
 #description
-TODO
+Learn how to configure your stores for deployment using `alokai.config.json`.
 
 #cta
-:::docs-arrow-link{to="/guides/multistore/tooling-and-concepts/configuration"}
+:::docs-arrow-link{to="/guides/multistore/tooling-and-concepts/deployment/configuration"}
 Next
 :::
 ::