Introduction

Microservices

Microservices enable applications to scale easily and to develop quickly, thus enabling innovation and speeding up time to market. The two main technologies that enable the development of microservices applications are Containers and Serverless. In recent years, Kubernetes (K8s) has been widely adopted for automating the deployment of infrastructure, scaling of resources, and managing containerized applications.

When we develop microservices, we need to follow the following best practices [1]:

• Use separate data storage for each microservice

• Keep code at a similar level of maturity

• Separate build for each microservice

• Assign each microservice with a single responsibility

• Deploy into containers

• Design stateless services

• Adopt domain-driven design

• Design micro frontend

• Orchestrating microservices

Amazon Elastic Kubernetes Service (EKS)

Utilize Amazon EKS to expose K8s Microservices hosted on private subnets to the Internet and on-premises networks.

Terraform

Further, HashiCorp Terraform Infrastructure as Code is a tool to deploy and operate containerized workloads quickly and efficiently.

Virtual Private Cloud (VPC)

• A highly available architecture that spans at least 2 Availability Zones.

• A VPC configured with public and private subnets, according to AWS best practices, to provide you with your own virtual network on AWS.

• Routes incoming internet traffic through an Amazon Route 53 public hosted zone.

• In the public subnets, managed Network Address Translation (NAT) gateways allow outbound internet access for resources in the private subnet.

• In the private subnets, Amazon EKS clusters with Kubernetes Worker Nodes -inside an Auto Scaling Group. Each node is an Amazon Elastic Compute Cloud (Amazon EC2) instance or AWS Fargate. Each cluster may contain the following:

  • Microservices applications and components.

  • Cert-manager.

  • An open-source logging and monitoring solution with Grafana, Prometheus.

  • ExternalDNS, which synchronizes exposed Kubernetes services and ingresses with Route 53.

• An Elastic Load Balancer to distribute traffic across the Kubernetes nodes.

• Amazon Simple Storage Service (Amazon S3) to store the files.

• Amazon Elastic File System (Amazon EFS) to provide storage for Grafana, Prometheus.

• Amazon Relational Database Service (Amazon RDS) for PostgreSQL to store application data.

• Amazon Elastic Container Registry (Amazon ECR) to provide a private registry.

• AWS Key Management Service (AWS KMS) to provide an encryption key for Amazon RDS, Amazon EFS, and AWS Secrets Manager.

• AWS Secrets Manager to replace hardcoded credentials, including passwords, with an API call.

• 🚦 The traffic is sent/receive to/from the on-premises network over the Virtual Private Network (VPN) or AWS Direct Connect connection.

Expose Microservices in a Hybrid Scenario

1. Inbound External & EKS Public Load Balancer

• Amazon Route 53 resolves incoming requests to the public Elastic Load Balancer (ELB) deployed by the AWS Load Balancer Controller.

• 🚦The AWS LB controller satisfies K8s services with Network Load Balancers (NLBs) and Kubernetes ingresses with Application Load Balancers (ALBs). You can also manage ingresses by implementing other ingress controllers like the NGINX ingress controller.

• 🚦The EKS-related ELBs forward traffic to applications. You can choose between the two modes [2]:

  • Instance mode: The traffic is sent to a worker node, then the service redirects traffic to the Pod.

  • IP mode: The traffic is directed to the IP of the Pod directly.

• 🚦If we’re using AWS Fargate for Amazon EKS, we will not have Worker Nodes but only the pod ENIs in the private subnets. You can only use ELBs with IP mode with AWS Fargate pods.

2. Inbound External & EKS Private Load Balancer

• Amazon Route 53 resolves incoming requests to the Private ELB deployed by the AWS Load Balancer Controller.

3. Outbound External

• When the pod in private subnets initiates an outbound request to the internet, the private route table forwards the traffic to the NAT Gateway (NGW).

• The public route table forwards the traffic from the NGW to the Internet Gateway (IGW).

4. Outbound Internal

• The pod in private subnets initiates an outbound request to the on-premises network. The private route table forwards the traffic to the Virtual Private Gateway (VGW).

• 🚦 You can also enable private access for your Amazon EKS cluster’s Kubernetes API server endpoint and limit, or completely disable, public access from the internet [3].

• 🚦Deal with Pod IP Exhaustion:
  Increase the IP addresses available to pods by adding dedicated subnets from the 100.64.0.0/10 and 198.19.0.0/16 ranges.

  • By adding secondary CIDR blocks to a VPC from the RFC 6598 address space (in the example 100.64.0.0/16), in conjunction with the CNI Custom Networking feature, it is possible for pods to no longer consume any RFC 1918 IP addresses in a VPC (in the example, pods are in subnets 100.64.0.0/19 and 100.64.32.0/19). Check out How do I use multiple CIDR ranges with Amazon EKS?

  • 💡 Moving to IPV6 also solves pod IP exhaustion, because you don’t need to work around IPv4 limits.

• 🚦Check out EKS VPC routable IP address conservation patterns in a hybrid network for Multi-Account settings to leverage the AWS Transit Gateway to scale this pattern across an enterprise to include multiple EKS clusters and an on-premises data-center.

References

• [1] https://www.linkedin.com/posts/alexxubyte_systemdesign-coding-interviewtips-activity-7082021558193418241-nw7Q

• [2] https://www.linkedin.com/posts/ankit-jodhani_10weeksofcloudops-10weeksofcloudops-aws-activity-7077706068096692225-iQyy

• [3] https://d1.awsstatic.com/architecture-diagrams/ArchitectureDiagrams/expose-microservices-using-eks-ra.pdf

• [4] https://kubernetes-sigs.github.io/aws-load-balancer-controller/v2.3/how-it-works/

• [5] https://aws.amazon.com/blogs/containers/de-mystifying-cluster-networking-for-amazon-eks-worker-nodes/

• [6] https://terraform.job4u.io/en/private-eks.html

• ✅ Youtube: https://youtu.be/UvMYMObzXb4
• ✅ Github: https://github.com/OceanSoftIO/Digital-Commerce

1. Gitpod Cloud Development Environment

Modern engineering teams are embracing cloud technologies and automating whenever possible, including infrastructure, CI/CD build pipelines, linting/formatting, and even writing code, to avoid costly errors and focus on product and customer value creation.

We will demonstrate how to use Gitpod to spin up an automated development environment in seconds so that you are always ready to code. After completing the guided tutorial below, you will be able to build and deploy open-source 🆓 Shopify-like Digital Commerce 💰 in minutes.

2. Cloud Development Environment in 1-Click

You can quickly set up a complete development environment in your browser with only 1-click and begin coding immediately.

• Click the button below to start a new cloud development environment using Gitpod: https://gitpod.io/#https://github.com/OceanSoftIO/Digital-Commerce

• You will need to authorize your GitHub account before you can use Gitpod.

• Upon clicking on Gitpod, a workspace will be opened in the browser that contains:

  • VS Code for editing code.
  • An embedded browser window in which the application is running.
  • Two terminal sessions: the left terminal can be used for entering commands, and the right terminal runs the eCommerce-Backend testing.

2.1. Generate Your Gitpod Config File:

gp init

2.2. Edit .gitpod.yml

## List the start up tasks. Learn more https://www.gitpod.io/docs/config-start-tasks/
tasks:

  - name: 1.1. backend
    ## working directory as `/ecommerce/backend`
    before: |
      npm install @medusajs/medusa-cli@latest -g
      cd backend
    init: |
      npm install
    command: |
      npm run dev
      # gp sync-done finished
    openMode: split-left

## List the ports to expose. Learn more https://www.gitpod.io/docs/config-ports/
ports:
  - port: 9000
    onOpen: ignore

2.3. Test ecommerce-backend

## List the start up tasks. Learn more https://www.gitpod.io/docs/config-start-tasks/
tasks:

  - name: 1. backend
    ## working directory as `/ecommerce/backend`
    before: |
      npm install @medusajs/medusa-cli@latest -g
      cd backend
    init: |
      npm install
    command: |
      npm run dev

  - name: 2. backend (test)
    ## working directory as `/ecommerce/backend`
    before: |
      cd backend
    init: |
      # echo "curl -X GET localhost:9000/store/products | python -m json.tool"
      echo "npm run seed"
    command: |
      echo "curl -X GET localhost:9000/store/products | python -m json.tool"

## List the ports to expose. Learn more https://www.gitpod.io/docs/config-ports/
ports:
  - port: 9000
    onOpen: ignore
  # - port: 8000
  #   onOpen: open-browser
  # - port: 7000
  #   onOpen: open-preview

cd backend

##
npm run seed

##
curl -X GET localhost:9000/store/products | python -m json.tool

3. docker compose on Gitpod

This Gitpod Docker Compose provides you with pre-built, ephemeral development environments in the cloud ⛅

3.1. Update project config in backend/medusa-config.js:

module.exports = {
  projectConfig: {

    // /** Option1 - SQLite (default): Development-like Environment */
    // database_database: "./ecommerce.sql",
    // database_type: "sqlite",

    /** Option2 - PostgresQL: For more production-like environment */
    redis_url: REDIS_URL,
    database_url: DATABASE_URL, //postgres connectionstring
    database_type: "postgres",

    store_cors: STORE_CORS,
    admin_cors: ADMIN_CORS,
  },
  plugins,
};

3.2. docker compose task

## List the start up tasks. Learn more https://www.gitpod.io/docs/config-start-tasks/
tasks:

  - name: 2.1. backend >> docker compose
    ## working directory as `/ecommerce/backend`
    before: |
      npm install @medusajs/medusa-cli@latest -g
      cd backend
    # init: |
    #   docker compose pull
    command: |
      docker compose up --build
      # gp sync-done finished
    openMode: split-left

  - name: 2.2. backend >> docker compose (test)
    ## working directory as `/ecommerce/backend`
    before: |
      cd backend
    init: |
      # curl -X GET localhost:9000/store/products | python -m json.tool
      echo "docker image ls"
      echo "docker container ls"
      echo "docker exec ecommerce-backend medusa seed -f ./data/seed.json"
    command: |
      # gp sync-await finished && \
      echo "curl -X GET localhost:9000/store/products | python -m json.tool"
    openMode: split-right

## List the ports to expose. Learn more https://www.gitpod.io/docs/config-ports/
ports:
  - port: 9000
    onOpen: ignore
  # - port: 8000
  #   onOpen: open-browser
  # - port: 7000
  #   onOpen: open-preview

3.2. To get started with Docker Compose on Gitpod, click on the "Open in Gitpod" button.

4. Lab #1: express-redis

## List the start up tasks. Learn more https://www.gitpod.io/docs/config-start-tasks/
tasks:

  - name: Start Redis Stack
    ## working directory as `/README/lab1.express-redis`
    before: |
      cd README/lab1.express-redis
    init: |
     docker compose pull
    command: |
     alias redis-cli="docker exec -it redis-stack redis-cli" 
     echo "Use redis-cli to interact with Redis here."
     docker compose up -d
     gp sync-done finished
    openMode: split-left

  - name: Start Express Application
    ## working directory as `/README/lab1.express-redis`
    before: |
      cd README/lab1.express-redis/backend
    init: |
      npm install
    command: |
      gp sync-await finished && \
      npm run dev
    openMode: split-right

  - port: 9999
    onOpen: open-preview
  - port: 6379
    onOpen: ignore

• Upon clicking on Gitpod, a workspace will be opened in the browser that contains:

  • VS Code for editing code.
  • An embedded browser window in which the application is running.
  • Two terminal sessions: the left terminal can be used for entering commands, and the right terminal runs the application using nodemon. Nodemon restarts the application when you save code changes.

5. Lab #2: elasticsearch-logstash-kibana

## List the start up tasks. Learn more https://www.gitpod.io/docs/config-start-tasks/
tasks:

  - name: Start ELK Elasticsearch Logstash Kibana
    ## working directory as `/README/lab2.elasticsearch-logstash-kibana`
    before: |
      cd README/lab2.elasticsearch-logstash-kibana
    init: |
     docker compose pull
    command: |
     docker compose up -d
     gp sync-done finished
    openMode: split-left

  - name: Test ELK
    ## working directory as `/README/lab2.elasticsearch-logstash-kibana`
    before: |
      cd README/lab2.elasticsearch-logstash-kibana
    init: |
      echo "[Test ELK] init ..."
    command: |
      gp sync-await finished && \
      echo "[Test ELK] command ..."
      echo "PORTS >> 5601 >> Open Preview"
    openMode: split-right

6. Next Steps

• 💎 Modernizing Full-Stack Applications with ⚡ Serverless Containers 🐳 and Infrastructure as Code ⛅

🎯 As the frontend for the Serverless Application on AWS, this React application has been bootstrapped with Create React App.

💎 The AWS CDK Construct cdk-spa for deploying Single-Page Application (Angular/React/Vue) to AWS S3 behind CloudFront CDN, Route53 DNS, Certificate Manager in minutes.

💎 The CDK Construct cdk-cognito for deploying Amazon Cognito to provide authentication, authorization, and user management for web & mobile applications.

1. Create a Serverless Application using the AWS Cloud Development Kit (CDK) ⚙️

This is the CDK source code for deploying a Serverless Application ⚡ on AWS, which includes the infrastructure for the ReactJS Frontend, NodeJS Backend, Cognito authentication, authorization, and user management, CodeBuild / CodePipeline DevOps CI/CD, and IAM / KMS / CloudWatch Operation.

• Step 1.1. Create an AWS CDK app cdk

  CDK_APP_ID=cdk
  mkdir $CDK_APP_ID && cd $CDK_APP_ID
  
  cdk init app --language typescript
  

• Step 1.2. Installing cdk-spa for deploying frontend

  npm install --save cdk-spa

  • cdk-spa Option 1. Basic setup needed for a non-SSL, non cached S3 website.
  • cdk-spa Option 2. S3 deployment will be created, which is fronted by a Cloudfront Distribution.
  • cdk-spa Option 3. The deployment of S3, Cloudfront Distribution, ACM SSL certificates, and Route53 hosted zones.

  💎 This CDK TypeScript Construct Library cdk-spa includes a construct CdkSpa and an interface CdkSpaProps to make deploying a Single Page Application (SPA) Website (React.js / Vue.js / Angular) to AWS S3 behind CloudFront CDN, Route53 DNS, Certificate Manager SSL as easy as 5 lines of code.

• Step 1.3. Usage of CDK constructs Serverless/cdk/lib/frontend-stack.ts

  import { StackProps, Stack } from 'aws-cdk-lib';
  import { Construct } from 'constructs';
  import { CdkSpa } from 'cdk-spa';
  
  interface Props extends StackProps {
    contentBucket: string;
  }
  
  export class FrontendStack extends Stack {
    constructor(scope: Construct, id: string, props: Props) {
      super(scope, id, props);
  
      /**
       * 1. Encrypted S3 Bucket
       * 2. Deploying a SPA-Website to AWS S3 behind CloudFront CDN
       * 3. Auto Deploy to/from Hosted Zone Name
       */
      new CdkSpa(this, 'CDK-SPA Website behind Cloudfront CDN', {
        bucketName: props.contentBucket,
        encryptBucket: true,
        // ipFilter: true,
        // ipList: ['1.1.1.1']
      })
        /* Option 1. Basic setup needed for a non-SSL, non vanity url, non cached S3 website. */
        .createSiteS3({
        // /* Option 2. S3 deployment will be created, which is fronted by a Cloudfront Distribution. */
        // .createSiteWithCloudfront({
        // /* Option 3. The deployment of S3, Cloudfront Distribution, ACM SSL certificates, and Route53 hosted zones. */
        // .createSiteFromHostedZone({
        //   zoneName: 'serverless.aws.oceansoft.io',
          indexDoc: 'index.html',
          websiteFolder: '../frontend'
        });
  
    }
  }
  

• Step 1.4. Usage of CDK Application Serverless/cdk/bin/cdk.ts

  #!/usr/bin/env node
  import 'source-map-support/register';
  import * as cdk from 'aws-cdk-lib';
  
  import { FrontendStack } from "../lib/frontend-stack";
  
  const APP_ID = "Serverless";
  
  const account = process.env.AWS_ACCOUNT;
  const region = process.env.AWS_REGION;
  const contentBucketName = `${APP_ID}-${account}-${region}-content`.toLowerCase();
  
  const app = new cdk.App();
  
  /**
   * 1. AuthStack
   * 2. BackendStack
   * 3. FrontendStack
   * 4. OpsStack
   * 5. DashboardStack
   */
  
  /* 3. FrontendStack */
  const frontend = new FrontendStack(app, APP_ID.concat("-Frontend"), {
    contentBucket: contentBucketName,
    // env: { account: account, region: region },
  });
  
  cdk.Tags.of(frontend).add("APP_ID", APP_ID);
  

• Step 1.5. CDK Deployment deploy.sh

  echo "Boostrap the AWS Account/Region you plan to deploy to ..."
  cdk bootstrap aws://${AWS_ACCOUNT}/${AWS_REGION}
  
  echo "Installing & building ..."
  npm install
  npm run build
  
  echo "deploy this stack to your AWS account/region"
  cdk deploy --all --require-approval never
  

• ⚠️ CDK v1 👇

  https://www.youtube.com/watch?v=3IC1edBb2BA

• ✅ Source Code: https://github.com/OceanSoftIO/Serverless/cdk

2. Deploying a CDK Application using AWS CloudShell 🆓

🆓 CloudShell provides you with a browser-based shell to run scripts and commands. It includes 1 GB of persistent storage per Region at no extra cost to you.

git clone https://github.com/OceanSoftIO/Serverless

cd Serverless/cdk
./deploy.sh

3. Create React Application frontend

• ✅ Frontend Tech Stack: ✅ React.js || ☑️ Next.js || ☑️ Angular || ☑️ Vue

• To boot up Create React App, use the following command-line:

  npx create-react-app frontend
  
  cd frontend
  npm start
  

• ☑️ Running Tests with the React Testing Library

  npm run test
  

• ☑️ Changing the App’s MetaData || Images || Other Types of Assets

• ☑️ Installing Dependencies

  npm install axios
  

• ☑️ Importing components

• ☑️ Styling React App with CSS

• ☑️ Building and Publishing the React App

  npm run build
  

4. Deploying Amazon Cognito cdk-cognito

💎 The CDK Construct cdk-cognito for deploying Amazon Cognito to provide authentication, authorization, and user management for web & mobile applications.

5. When & Why & Should Developers consider Micro-frontends

📚 Micro-Frontends in context

6. Server-Side Rendering Micro-Frontend

• Micro-frontends are a very effective way to embrace distributed systems on the front end using a Serverless approach. As every Serverless Micro-Frontend returns an HTML fragment (HTML-on-the-wire), a UI composer stitches together these independent components, creating a seamless user experience.

  • This architecture starts with Amazon CloudFront that has two origins: an Amazon Simple Storage Service (Amazon S3) bucket, and a public Application Load Balancer.

  • The Amazon S3 bucket contains all the static files to be served for the browser, such as common micro-frontend dependencies, images, or CSS files. Additionally, it contains the templates required by the UI composer for placing each micro-frontend on an HTML page.

  • The UI composer is an AWS Fargate cluster that combines different micro-frontends into one and serves the results to the browser in real-time, streamlining the response to improve the performance of web applications. Using an Amazon ElastiCache cluster can increase performance even further by caching some micro-frontend output or the entire page.

  • Use AWS Systems Manager Parameter Store to collect all the micro-services endpoints. They can be HTTP endpoints, or Amazon Resource Names (ARNs) of a specific service such as AWS Lambda or AWS Step Functions. By decoupling, you maintain independence between the teams working on the application.

  • The serverless micro-frontend is composed of AWS Lambda and Amazon DynamoDB for storing the data that will be rendered. The output is an HTML fragment ready to be embedded in the template composed by the UI composer.

  • Utilizing Amazon API Gateway, which validates tokens or API keys, ensures that only your application can access those endpoints if you work with third parties in the same application.

  • Step Functions Express provides a low-code solution for creating micro-frontends. Step Functions' integration with over 200 services allows you, for example, to retrieve data natively from Amazon DynamoDB and delegate only the rendering of that data to an AWS Lambda function.

🎯 Deploy Your first Web Application in minutes on Heroku || AWS AppRunner & RDS (Free-Tier 🆓)

1. Iterative Application Modernization

Monolith to MicroServices: Many Monolithic Applications generate revenue for your company by adding value to your customers. You may have heard statements such as "let's move to a MicroService-based Architecture", but "we must deal with the Data Tier first".

How do we get there safely when we are heavily dependent on the application ⁉️

✅ Martin Fowler’s Strangler Pattern 📚: This methodology has been applied to moving specific data sets from a multi-terabyte Monolithic Database to a Purpose-built Database (SQL: MySQL / Postgres; NoSQL: MongoDB / DynamoDB), and utilizing a Data Lake to improve data access and performance.

• https://www.linkedin.com/posts/nnthanh_migrating-monolithic-applications-with-the-activity-6775946159061127169-XC9h
• https://www.slideshare.net/SmartBizVN/migrating-monolithic-applications-with-the-strangler-pattern

[Example] eCommerce Breaking-down the Monolith (Data-tier and App-tier)

• We have separated Shipping Service Data into a purpose-built database and a MicroService designed to handle shipping. With the newly developed Shipping Service, you will have the opportunity to develop MicroServices that focus on one job and do it extremely well.
• The Orders Service will come next, and Inventory Service will get their own MicroServices.
• Shopping Cart Service remain in the Monolith to ensure that customer service is not disrupted while the application is rearchitected. Once all monolithic capabilities have been replaced by MicroServices, we can now eliminate the monolith-app. Note that both Monoliths and MicroServices will coexist for a period of time.

☑️ Additionally, you may also use Adapter pattern and Façade pattern.

2. 🆓 [Dev/Test] Users < 10,000

• 🥇 Multi-AZ
• 🥇 Elastic Load Balancing between tiers
• 🥇 Auto Scaling
• 🎖️ Service-Oriented Architecture (SOA): Split Tiers into individual SOA Services.

Lab 1. Hosting Apps on Heroku

☑️ TODO: https://heroku.com/deploy?template=https://github.com/OceanSoftIO/ecommerce/

⚠️ Heroku Free-Tier: Heroku Pricing || Where Can Heroku Free Tier Users Go?

• [Example] This application has the following components:

  

  • Backend: Node.js REST API built with Express.js with resource endpoints that use Client to handle database operations against a PostgreSQL database (e.g., hosted on Heroku).
  • Frontend: Static HTML page to interact with the API.

Lab 2. Deploy Your first Web Application in minutes

• ☑️ TODO - Build and deploy solutions on AWS using AWS App Runner and Amazon RDS 🆓: https://github.com/OceanSoftIO/Terraform/tree/feature/AppRunner

  

3. 🥈 [Staging]

• 🥈 Serving content smartly (Cloud Storage/S3, CDN/Cloudfront)
• 🥈 Caching off databases
• 🥈 Moving state-off tiers that auto scale

4. 🥉 Production

• 🥉 Monitoring, metrics, and logging: Deeply analyze your entire stack then fine-tuning of your application.

  

• 🥉 Going from Multi-AZ to Multi-Region

• 🥉 Database:

  • Federation: Splitting into multiple databases based on function
  • Sharding: Splitting one data set across multiple hosts

  • Moving some functionality to other types of databases (NoSQL, Graph)

    

5. Next Steps ⚡

• 🏅 Service-Oriented Architecture (SOA) of features/functionality

• 🏅Build serverless whenever possible ⚡

  

🎯 Deliverables:

• 🐳 Medusa eCommerce Backend: Node.js
• ⚡ Medusa eCommerce Admin: Gatsby
• ⚡ Medusa eCommerce Storefront: Next.js

🌥️ The cloud journey generally involves migrating and modernizing websites and apps, including building and hosting websites, developing web and mobile apps, and monitoring and managing them. This hands-on series illustrates how to build a production-ready Headless CMS and Headless eCommerce using Jamstack (stands for JavaScript, API, and Markup) on Cloud (Heroku, AWS ...) 🌥 .

1. ✅ ⚡ Building a Production-Ready Headless CMS with Jamstack (Gatsby and Contentful) 🎁
2. ✅ 🐳 Dockerizing Strapi - Open-Source NodeJS Headless CMS
3. ☑️ 🐳 Medusa Headless-eCommerce - Open-Source Shopify alternative ⚡

Introduction to Headless eCommerce

Medusa is an open-source API-first headless commerce platform giving engineers the foundation for building unique and scalable digital commerce projects quickly.

The Shopify eCommerce platform simplifies the creation of e-commerce stores for merchants and businesses who don't need to learn the technical details of setting up shops and want to get started quickly. However, Medusa is built for developers and focuses on providing a great developer experience with an abstraction-based architecture, ease of setup, strong documentation, and a supportive community.

Headless eCommerce Architecture

The Headless eCommerce platform collects, maintains, and distributes content without using the Frontend layer since it has been decoupled and eliminated, leaving only the Backend layer.

Backend Developers can then provide and retrieve things like product items, blog posts, and product reviews to any device using REST/GraphQL APIs, while Frontend Developers can present that fetched data in their own beautiful format using whichever framework they prefer, such as ReactJS, VueJS, Angular, etc.

🐳 Medusa eCommerce Backend: Node.js

Like Shopify, Medusa offers a similar set of core ecommerce features, including payment and checkout, cart-functionality, fulfillment flow, shipping options, customer profiles (for customer-specific pricing), advanced promotions (such as coupons and discounts), and product and stock management.

Despite Shopify's simplicity, most of its pros and features are a result of its monolithic architecture, which is also a weakness.

Medusa's open-source and abstraction-based architecture allows you to customize and compose your store specifically to suit each individual use case. Using Medusa, you can alter the core set up to fit your needs, or you can extend Medusa's APIs to extend functionality.

echo "Install the Medusa CLI"
yarn global add @medusajs/medusa

medusa new backend
# medusa new backend --seed

cd backend
# medusa develop
yarn start

⚡ Medusa eCommerce Admin: Gatsby

For non-technical store managers, an out-of-the-box admin panel provides built-in flows for claims, returns, and exchanges, allowing end-users to self-serve. Shopify, however, offers integrated marketing and sales analytics. The Medusa admin panel, however, offers greater customizability due to its extensible and composable architecture.

⚡ Medusa eCommerce Storefront: Next.js

With Shopify, you can easily set up themed solutions that have a great starter package with a variety of available themes. Shopify provides Shopify Plus (starting at 2,000$/month) which allows developers to go headless through the Hydrogen setup while developing functionalities and completely customizing the storefront.

The Medusa Frontend and Backend are decoupled, so the storefront functionality and design can be customized without interfering with the Backend. Developers can then use Next.js or Gatsby or any other front-end framework of their choice.

• Create Next.js Starter:

  Open the terminal and use the following command to create an instance of your storefront:

  npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa storefront
  
  cd storefront
  cp .env.template .env.local
  

  Now you have a storefront codebase that is ready to be used with your Medusa server.

• Link Storefront to Your Server

  By default, the storefront is linked to the server at the URL localhost:9000. If you need to change that, create the file .env in the root of your Next.js starter and add a new variable:

  NEXT_PUBLIC_MEDUSA_URL=<BACKEND_URL>

  Make sure to replace with the URL of your Medusa server.

• Update the STORE_CORS variable

  By default, the storefront runs at localhost:8000 and the backend uses that URL to avoid CORS errors. If you need to change the URL or port, in .env file in the root of your Medusa Server add the following new variable:

  STORE_CORS=

  Make sure you replace with the URL to your storefront.

• Start your Store

  To start your store, first, you need to run the Medusa server. In the directory that holds your Medusa server run the following:

  yarn start

  Then, in the directory that holds your Next.js storefront, run the following command:

  yarn dev

  Now, open the storefront at localhost:8000 (or the URL/port you specified) and you’ll see your store and the products!

🏁 Hooking up your Headless eCommerce Server with the Storefront is very easy using Medusa! You can now have your entire Server up and running with the products, cart, and checkout functionalities.

🎯 Deliverables:

• Strapi CMS Backend Template: https://www.npmjs.com/package/strapi-blog
• Strapi CMS Backend: https://github.com/OceanSoftIO/cms-blog/tree/main/backend
  • Dockerfile
  • Dockerfile.prod
  • docker-compose.yml

🌥️ The cloud journey generally involves migrating and modernizing websites and apps, including building and hosting websites, developing web and mobile apps, and monitoring and managing them. This hands-on series illustrates how to build a production-ready Headless CMS and Headless eCommerce using Jamstack (stands for JavaScript, API, and Markup) on Cloud (Heroku, AWS ...).

1. ✅ ⚡ Building a Production-Ready Headless CMS with Jamstack (Gatsby and Contentful) 🎁
2. ✅ 🐳 Dockerizing Strapi - Open-Source NodeJS Headless CMS
3. ☑️ 🐳 Medusa Headless-eCommerce - Open-Source Shopify alternative ⚡

1. Overview of Strapi Headless CMS

The Strapi Headless CMS is an Open-Source, Node.js platform for creating, managing, exposing and sharing content-rich experiences.

Traditional or monolithic Web-first CMS, such as WordPress, combine the frontend (website design and layout) and backend (the interface for editing and creating content) into a single application. The next-generation Content-first Headless CMS use an API for content delivery and allow complete separation of the backend (creation and storage) and frontend (design and deployment). Headless architecture not only rewards better performance and flexibility but also provides stronger security by making it nearly impossible for end-users to access the backend.

Developers are free to focus on designing amazing frontends that meet the needs of their customers because of all these benefits.

• Frontend: Developers can use their preferred frontend technology to deliver high-quality content experiences while quickly integrating features like authentication (via social media logins), content delivery, and payment processing into a full-fledged business application.
• REST & GraphQL API: The Strapi backend API makes content accessible and displayable on any device via a GraphQL or REST API. However, the exclusive focus is GraphQL API.
• Database Independent: A variety of database systems can be configured, including PostgreSQL, MySQL, MongoDB, and SQLite. However, we only configure Strapi for use with PostgreSQL.

2. Installing Strapi CMS-Backend

• 🚦 Prerequisites

  • 👨‍💻 Setup Development and Testing Environment on MacOS
  • ✅ Node.js v16
  • ✅ Yarn v1
  • ☑️ Gatsby CLI

• Option 1. Git clone from https://github.com/OceanSoftIO/cms-blog.git

  git clone https://github.com/OceanSoftIO/cms-blog.git
  cd cms-blog
  

• Option 2. Install Strapi CMS Backend with the blog schema template outside of the frontend directory on your machine.

  echo "Strapi V4 template: https://github.com/OceanSoftIO/cms-blog/tree/main/template"
  yarn create strapi-app backend --quickstart --template strapi-blog
  
  echo "Strapi V3 OLD-version !!!"
  # yarn create strapi-app cms --quickstart --template https://github.com/OceanSoftIO/cms-blog
  

• Following the installation, Strapi’s control panel will open in your browser, where you can register the admin user and create content.

• Frontend (Gatsby or Next.js) integration

2.1. Powerful CMS-Backend GraphQL APIs

cd cms-blog/backend

yarn install
yarn develop

• 🌏 http://localhost:1337/admin

• 🎁 Installation Service >> 🔒 Postman-GraphQL 💲

2.2. Testing and Deploying the Strapi API

3. Docker Setup

Developers are faced with the task of launching a development environment that has different software packages of certain versions. Fortunately, Docker solves this problem in the modern development world.

Creating Dockerfile & docker-compose.yml

  # cd cms-blog/backend
  # cat Dockerfile
  # cat docker-compose.yml

• 🐳 Dockerfile

  🐳 Creating a new Dockerfile: If you are using YARN, please use the following 👇

  FROM node:16
  ## Installing libvips-dev for sharp Compatability
  RUN apt-get update && apt-get install libvips-dev -y
  
  # FROM node:16-alpine
  ## Installing libvips-dev for sharp Compatability
  # RUN apk update && apk add  build-base gcc autoconf automake zlib-dev libpng-dev nasm bash vips-dev
  
  ARG NODE_ENV=development
  ENV NODE_ENV=${NODE_ENV}
  WORKDIR /opt/
  COPY ./package.json ./yarn.lock ./
  ENV PATH /opt/node_modules/.bin:$PATH
  RUN yarn config set network-timeout 600000 -g && yarn install
  WORKDIR /opt/app
  COPY ./ .
  RUN yarn build
  EXPOSE 1337
  
  CMD ["yarn", "develop"]
  

• 🐳 Dockerfile.Prod

  🐳 Optimizing your Dockerfile ☠️, then please use the following 👇

  The following are the methods by which we can achieve docker image optimization.

  

  • Using distroless/minimal base images
  • Multistage builds
  • Minimizing the number of layers
  • Understanding caching
  • Using Dockerignore
  • Keeping application data elsewhere

  FROM node:16-alpine as build
  ## Installing libvips-dev for sharp Compatability
  RUN apk update && apk add build-base gcc autoconf automake zlib-dev libpng-dev vips-dev && rm -rf /var/cache/apk/* > /dev/null 2>&1
  ARG NODE_ENV=production
  ENV NODE_ENV=${NODE_ENV}
  WORKDIR /opt/
  COPY ./package.json ./yarn.lock ./
  ENV PATH /opt/node_modules/.bin:$PATH
  RUN yarn config set network-timeout 600000 -g && yarn install
  WORKDIR /opt/app
  COPY ./ .
  RUN yarn build
  
  FROM node:16-alpine
  RUN apk add vips-dev
  RUN rm -rf /var/cache/apk/*
  ARG NODE_ENV=production
  ENV NODE_ENV=${NODE_ENV}
  WORKDIR /opt/app
  COPY --from=build /opt/node_modules ./node_modules
  ENV PATH /opt/node_modules/.bin:$PATH
  COPY --from=build /opt/app ./
  EXPOSE 1337
  CMD ["yarn", "start"]
  

• Quick tour of Dockerfile: 👇

  🐳 To get started, let's take a quick tour of Dockerfile: 👇

  • Initially, we'll use node:16 (~330 MB) or node:16-alpine (~39 MB) as our base image.
  • We'll install some libraries, like libvips-dev for sharp compatibility, with -y, so say yes to everything.
  • The node environment AVG will be set to development by default so we don't have to provide this each time.
  • The ENV allows us to override it if we want to switch from development to production.
  • We'll define our file paths and whatnot in the /opt WORKDIR working folder inside our container.
  • We copy package.json and yarn.lock (or package-lock.json if you're using npm) into our work directory. Docker caches each layer, so doing this first will speed up our build process.
  • Docker then knows where to find our node_modules
  • In case of network problems or a bit of slow internet, we will set a large timeout 600000 to allow extra time.
  • Afterwards, yarn install installs all dependencies.
  • Then we change the directories to /opt/apps
  • Next, we copy the project we created in step 1, cms-backend, into this folder.
  • We then run yarn build to build our MEAN project.
  • Finally, we expose port 1337 and tell Docker to run yarn develop

• .dockerignore 👇

  🐳 Docker Ignore: Create a file called .dockerignore: 👇

  .tmp/
  .cache/
  public
  .git/
  build/
  node_modules/
  data/
  

  ✍️ These folders in .dockerignore will be skipped ⛔️ by Docker 🐳 since they are not necessary.

4. Building & Running the Docker Image

• 1. Building the Docker Image

  docker build -t cms-backend:latest .

  • The name of the docker image is cms-backend, and it's tagged with :latest
  • Lastly, grab a cup of coffee ☕️, normally a few minutes , and sit back while Docker does its magic 🪄

  docker system prune --all --force

• 1. Running the Docker Image

  docker run -d -p 1337:1337 cms-backend

  • Docker will run the image cms-backend, or whatever you called your project, 🤔 on port 1337.
  • -d means detached and is a fancy way of saying "Runs in the background"

  • Tip: To use strapi on another port while developing, change the first part of the run port.

    docker run -d -p 8888:1337 cms-backend

    run on port 8888 👍

  • Finally, run on port 1337 👍

✍️ We are currently using an SQLite database, which is always inside the container. Whenever we stop a container, we lose all changes. Using docker-compose, we can use a Postgres database and run multiple instances of Docker if needed.

5. Utilizing docker-compose for the next level

• ⬆️ https://github.com/Academy4U/docker/blob/docker/strapi/README.Strapi.md

• 🪄 Think of docker-compose as a way to make different steps or services that we want to run.

• 🔔 https://github.com/Academy4U/docker/blob/docker/strapi/strapi/docker-compose.yml

• config/database.js

  ⚙️ config/database.js 👇

  const path = require('path');
  
  // module.exports = ({ env }) => ({
  //   connection: {
  //     client: 'sqlite',
  //     connection: {
  //       filename: path.join(__dirname, '..', env('DATABASE_FILENAME', '.tmp/data.db')),
  //     },
  //     useNullAsDefault: true,
  //   },
  // });
  
  /** PostgreSQL Database */
  module.exports = ({ env }) => ({
   connection: {
     client: env("DATABASE_CLIENT", "postgres"),
  
     connection: {
       host:     env("DATABASE_HOST", "127.0.0.1"),
       port:     env.int("DATABASE_PORT", 5432),
       database: env("DATABASE_NAME", "cms"),
       user:     env("DATABASE_USERNAME", "cms"),
       password: env("DATABASE_PASSWORD", "cms"),
     },
     debug: false,
   },
  });
  

• .env

  ⚙️ .env 👇

  env HOST=0.0.0.0 PORT=1337 ... DATABASE_HOST=localhost DATABASE_PORT=5432 # DATABASE_PORT=3306 DATABASE_NAME=cms DATABASE_USERNAME=cms DATABASE_PASSWORD=cms NODE_ENV=development DATABASE_CLIENT=postgres # DATABASE_CLIENT=mysql

  🐳 In the root of the project, create a file called docker-compose.yml. Due to the YAML format, spacing matters, so I've used spaces rather than tabs 👇

  version: "3"
  services:
   cms:
     container_name: cms
     build: .
     image: cms:latest
     restart: unless-stopped
     env_file: .env
     environment:
       DATABASE_CLIENT: ${DATABASE_CLIENT}
       DATABASE_HOST: cmsDB
       DATABASE_NAME: ${DATABASE_NAME}
       DATABASE_USERNAME: ${DATABASE_USERNAME}
       DATABASE_PORT: ${DATABASE_PORT}
       JWT_SECRET: ${JWT_SECRET}
       ADMIN_JWT_SECRET: ${ADMIN_JWT_SECRET}
       DATABASE_PASSWORD: ${DATABASE_PASSWORD}
       NODE_ENV: ${NODE_ENV}
     volumes:
       - ./config:/opt/app/config
       - ./src:/opt/app/src
       - ./package.json:/opt/package.json
       - ./yarn.lock:/opt/yarn.lock ##Replace with package-lock.json if using npm
       - ./.env:/opt/app/.env
     ports:
       - "1337:1337"
     networks:
       - cms
     depends_on:
       - cmsDB
  
   cmsDB:
     image: postgres:12.0-alpine
     container_name: cmsDB
     platform: linux/amd64 ##for platform error on Apple M1 chips
     restart: unless-stopped
     env_file: .env
     environment:
       POSTGRES_USER: ${DATABASE_USERNAME}
       POSTGRES_PASSWORD: ${DATABASE_PASSWORD}
       POSTGRES_DB: ${DATABASE_NAME}
     volumes:
       - cms-data:/var/lib/postgresql/data/ ##using a volume
       #- ./data:/var/lib/postgresql/data/  ##if you want to use a bind folder
     ports:
       - "5432:5432"
     networks:
       - cms
  
  volumes:
     cms-data:
  
  networks:
   cms:
     name: cms
     driver: bridge
  

  📚 I'll explain what all of this means: 👇

  • version - Docker-compose version 3
  • services - We are defining two services cms and cmsDB
  • cms - The name of the service we defined
  • container_name - The name of the container. You can call it whatever you want.
  • build - Telling cms to build the image in our project folder ..
  • image - The image name we want to build
  • restart - Unless we STOP or take down the container, it will keep restarting.
  • env_file - Providing a .env file containing the environmental variables we should keep secret.
  • environment - Here we define all the variables we want to use. Our .env file will have $[THISISOURNAME] as a placeholder.
  • volumes - mounting files into the container. Now this could be ./:/opt/app, but we might want to develop locally and just run our development server locally we are binding folders and some files to not bind node_modules There is some info about that here.
  • ports - What ports we want to expose. Note: You can change the left side to another port, such as 8080:1337, but remember that the right side needs to be 1337, which is the port inside the container where CMS is running.

  • networks - Set up a docker network so that our containers can communicate together. The Docker-Network tells Docker that before running the cms container, we need to run the postgresDB container first. This saves us some errors when we start the CMS container without a database.

  • Similarly, we give Postgres a name, but we use the official postgres:12.0-alpine image instead of building it ourselves. In addition, we are creating a volume called cms-data to hold our database.

  • ✍️ When installing Docker Desktop for MacOS, docker-compose is also automatically installed; however, for Linux, you must separately install it.

🚀 Running our project

• [ ] 🐳 Local: This will now spin up just a Postgres database, and we can run and change files just like working on Strapi anywhere.

  docker-compose up -d cmsDB && yarn develop

• [x] 🐳 Full: This will run Strapi inside a Docker Container and the database in its own container.

  docker-compose up -d

Next Steps

• 1️⃣ Backend Deployment using Render, Heroku, GCP, AWS
• 2️⃣ Frontend: Gatsby Cloud, Netlify, AWS Amplify
• 3️⃣ Infrastructure as Code: Build and Deploy Application to AWS App Runner || ECS/EKS using Terraform and AWS CodePipeline

🎯 Implementing Headless Architecture for Content Management System (CMS) using Jamstack (JavaScript, APIs, and Markup) and Cloud Hosting (Gatsby Cloud, Netlify, AWS Amplify) ⚡

🚀 Live Demo: https://academy.job4u.io/

🌥️ The cloud journey generally involves migrating and modernizing websites and apps, including building and hosting websites, developing web and mobile apps, and monitoring and managing them. This hands-on series illustrates how to build a production-ready Headless CMS and Headless eCommerce using Jamstack (stands for JavaScript, API, and Markup) on Cloud (Heroku, AWS ...).

1. ✅ ⚡ Building a Production-Ready Headless CMS with Jamstack (Gatsby and Contentful) 🎁
2. ☑️ 🐳 Dockerizing Strapi - Open-Source NodeJS Headless CMS
3. ☑️ 🐳 Medusa Headless-eCommerce - Open-Source Shopify alternative ⚡

Incremental Architecture Approach

We'll look at a traditional waterfall project timeline, in which all evaluation is done upfront, step by step, before approval and kickoff. After that, you add the content to the CMS, develop the site, do some launch preparation, and then launch it 🚀.

Using incremental architecture, project timelines can be reduced by making architectural decisions during the project rather than delaying the start of the project. You can also synchronize work across multiple systems, such as Headless CMS, Headless eCommerce, and Analytics.

By mocking your content during initial development, you can add content to your CMS while developing your site. You can also add content to your CMS/eCommerce Backend while working on your frontend.

Headless Architecture for CMS

Traditional or monolithic Web-first CMS, such as WordPress, combine the frontend (website design and layout) and backend (the interface for editing and creating content) into a single application.

The next-generation Content-first Headless CMS use an API for content delivery and allow complete separation of the backend (creation and storage) and frontend (design and deployment). Headless architecture not only rewards better performance and flexibility but also provides stronger security by making it nearly impossible for end-users to access the backend.

Headless CMS with Jamstack

In the diagram below, Jamstack's typical website is made up of several types of systems, such as Gatsby and Contentful/Strapi CMS, that are fast, secure, and offer a great digital experience.

By utilizing modular architecture, you can not only achieve better business results, but also do so in an accelerated timeframe. This proves to all your stakeholders and clients the value of new technologies.

Reference: Ship your Contentful website faster with incremental architecture

Cloud Hosting (Gatsby Cloud, Netlify, AWS Amplify)

• ✅ AWS Amplify
• ☑️ Gatsby Cloud
• ☑️ Netlify

[Webhook] AWS Amplify & Contentful

• [ ] .env --> Amplify > Environment variables

• [ ] 1. Create an incoming webhook to publish content updates.

  • [x] Choose App Settings > Build Settings > Incoming webhooks, and then choose Create webhook. This webhook enables you to trigger a build in the Amplify Console on every POST to the HTTP endpoint.
  • [x] After you create the webhook, copy the URL (it looks like https://webhooks.amplify.ap-southeast-1.amazonaws.com/prod/webhooks?id=XXX)

• [ ] 2. Go back to the Contentful dashboard, and choose Settings > Webhooks. Then choose Add Webhook. Paste the webhook URL you copied from the Amplify Console into the URL section and update the Content Type to application/json. Choose Save.

📚 Checklist Template 🎓

🎁 Installation Service: Gatsby & Contentful CMS-Blog

💲 Service Fee: $500 (Gatsby Theme + Support + Installation Service)

⌛ Turnaround: 1 Business Day

🎯 Within 1 business day, you will receive the source code for your Amplify/Netlify-hosted website, as well as a temporary URL.

Source Code: https://github.com/OceanSoftIO/docs.git

WHAT is Docs-as-Code

• ✍️ Documentation as Code (Docs-as-Code) is a growing trend in software documentation, in which documentation is written using the same tools as code:

  • Issue Trackers, Version Control (Git), Code Reviews: Github
  • Plain Text Markup (Markdown, Asciidoc, reStructuredText): Markdown
  • CI/CD, Automated Tests: AWS Amplify

• 🎁 The product team needs to follow the same workflows as the development teams. As a result, both writers and developers feel ownership of documentation and work together to create a valuable source of information:

  • Adopt an “agile” approach to content creation
  • Content is the responsibility of the entire team, not just the technical writers
  • The culture of adapting and improving content and processes over time.

WHY We like Docs-as-Code ?

In general, Docs-as-Code offers the following benefits for Technical Documentation:

1. By integrating with the Development Team more effectively, the Release Technical Writer can deliver higher-quality documentation (information architecture, customer experience, etc.) more quickly through collaboration with multiple voices.
2. Developers often write the first draft of documentation, avoiding the documentation becoming a bottleneck. The writers then define and automate the process, including approval gates, automated quality checks, such as spelling and grammar, and external content publishing, such as https://solution.job4u.io or https://oceansoftio.github.io/docs.
3. New features can't be merged if they don't include documentation, which incentivizes developers to document them immediately. Furthermore, Documents-as-Code eliminates the need for proprietary tools for technical writing and publishing.

HOW to Create and Manage Quality Documentation

The above diagram depicts a simple content authoring, review, and publishing workflow:

1. The documentation is located in the docs folder in the docs branch. We use an IDE like VSCode to create markdown files as well as extensions for diagramming tools like DrawIO, so you can also version control your diagrams!
2. Authors publish the branch to the GitHub source control system. Technically, they don't have to do this every time, but it's good practice as a backup.
3. Authors create a Pull Request (PR) when they are ready to submit content changes.
4. Content Editors will receive a notification when a new PR is published. Upon reviewing the content, the Editor can approve or reject the submission; the Editor can add comments so the author knows what must be approved.
5. Once a PR is created/updated (following feedback), an automated pipeline will execute various quality checks against the content.
6. Once the editor has approved the PR, the content can be merged into the main branch.
7. Content from the main branch can be built and deployed automatically to users using AWS Amplify CI/CD (Continuous Integration and Continuous Delivery) Pipeline.

Adopting Docs-as-Code: from Hackathon to Production

Ideally, the architecture document should be prepared in Markdown format and managed in a Git repository to ensure high quality, manageability, version control, and traceability.

We use the following developer tools and processes to create and deliver content:

• Documentation template: VS Code || Intellij

  • [x] Markdown *.md: https://solution.job4u.io/
  • [x] Ascidoc: https://github.com/OceanSoftIO/docs/asciidoc
  • [ ] Restructured Text *.rst

• Developer-based workflows: GitHub || GitLab

  • [x] Version Control using tools, such as Git
  • [x] Change control driven though bugs and feature requests tickets
  • [x] Content reviews and merges

• Static Site Generators (SSG)

  • [x] Mkdocs --> https://solution.job4u.io
  • [x] Hugo --> https://terraform.job4u.io/ || https://cdk.job4u.io/
  • [ ] [Jekyll](https://jekyllrb.com/
  • [ ] Docusaurus
  • [ ] Sphinx (reStructuredText)
  • [ ] Middleman

• CI/CD Pipeline:

  • [x] AWS Amplify
  • [x] GitHub Actions: https://oceansoftio.github.io/docs
  • [ ] GitLab Pipeline
  • [ ] Netlify

• Script-Based Design Tools & Architecture Templates

  • [x] Mermaid (UML): https://mermaid-js.github.io/mermaid/#/
  • [ ] PlantUML (UML, C4, Mindmap) : https://plantuml.com/
  • [ ] Structurizr (C4) : https://structurizr.com/

Docs for Agile Delivery in Practice

• [x] Installing MkDocs & Material Design theme for MkDocs

  pip install mkdocs mkdocs-material
  mkdocs new docs
  # ~/Library/Python/3.9/bin/mkdocs new docs
  

• ✅ Branding

  • [x] Adding your Logo to Header
  • [x] Adding your Favicon
  • [x] Adding your Social Media links to Footer
  • [x] Adding your Brand's colors
  • [ ] Adding fonts to match your brand

✅ Markdown Extensions

• [x] https://oceansoftio.github.io/docs/mkdocs-alternatives

✅ AWS Amplify CI/CD Pipeline

• [x] amplify.yml
• [x] Amplify >> Previews
• [x] Amplify >> Notifications

Live Demo:

MkDocs

⚡ You can create an online workshop in one minute using this open-source Jamstack Static Site Generator (SSG) Template ⏱️

```
git clone https://github.com/OceanSoftIO/docs
cd mkdocs

mkdocs serve
```

✅ solution.job4u.io

🔗 https://github.com/OceanSoftIO/docs/tree/main/mkdocs

Hugo

```
git clone -b hugo https://github.com/OceanSoftIO/docs
cd docs/hugo
git submodule init && git submodule update --checkout --recursive

hugo server --port 8080
```

🔗 http://localhost:8080/

References

1. Docs Like Code - Anne Gentle
2. Modern Technical Writing - Andrew Etter
3. Amazon Web Services (AWS) told the story of their team’s move to docs as code: what worked, what didn’t, what’s next.