From 84716b40889ae41e7a5661ad2160eb8ec82e5b62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20G=C3=B3ral?= Date: Wed, 19 Feb 2025 19:04:53 +0700 Subject: [PATCH 1/4] docs(TF-408): how deployment works --- .../4.deployment/6.deployment.md | 136 +++++++++++++++++- 1 file changed, 134 insertions(+), 2 deletions(-) diff --git a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md index 2c6a727872..6d2f5bbcec 100644 --- a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md +++ b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md @@ -7,14 +7,146 @@ 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 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/` 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 a fully independent version of 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///.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///.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 + +### 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 ::: :: From 370fd75bb60a49c7c4c81e9b379e653756f224d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20G=C3=B3ral?= Date: Fri, 21 Feb 2025 16:38:19 +0700 Subject: [PATCH 2/4] chore: add link to file-based inheritance --- .../2.tooling-and-concepts/4.deployment/6.deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md index 6d2f5bbcec..22788e45f3 100644 --- a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md +++ b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md @@ -36,7 +36,7 @@ Let's explore each stage in detail. ### 1. Store Composition -The journey begins with store composition. The CLI uses the file-based inheritance rules to compose the stores by: +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 From dcb4f84db877933d4c59723393eadb7d49510365 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20G=C3=B3ral?= Date: Fri, 21 Feb 2025 16:40:39 +0700 Subject: [PATCH 3/4] docs: maximum compatibility --- .../2.tooling-and-concepts/4.deployment/6.deployment.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md index 22788e45f3..b2817e243d 100644 --- a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md +++ b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md @@ -118,6 +118,7 @@ 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 From 6f91dde8c709b7285c6dd7a2c12d71bacbd72041 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tomasz=20G=C3=B3ral?= Date: Fri, 21 Feb 2025 19:34:54 +0700 Subject: [PATCH 4/4] chore: elaborate more on independent versions --- .../2.tooling-and-concepts/4.deployment/6.deployment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md index b2817e243d..a76ab39d3f 100644 --- a/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md +++ b/docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/6.deployment.md @@ -61,7 +61,7 @@ apps/ │ │ ├── eu/ ``` -The CLI copies files to their respective store directories, creating a fully independent version of each store: +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/