feat: devcontainer (apache#1283)

.devcontainer/Dockerfile

@@ -0,0 +1,14 @@
+# [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 18, 16, 14, 18-bullseye, 16-bullseye, 14-bullseye, 18-buster, 16-buster, 14-buster
+ARG VARIANT=16-bullseye
+FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:0-${VARIANT}
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment if you want to install an additional version of node using nvm
+# ARG EXTRA_NODE_VERSION=10
+# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"
+
+# [Optional] Uncomment if you want to install more global node modules
+# RUN su node -c "npm install -g <your-package-list-here>"

.devcontainer/base.Dockerfile

@@ -0,0 +1,55 @@
+# [Choice] Node.js version (use -bullseye variants on local arm64/Apple Silicon): 18-bullseye, 16-bullseye, 14-bullseye, 18-buster, 16-buster, 14-buster
+ARG VARIANT=16-bullseye
+FROM node:${VARIANT}
+
+# [Option] Install zsh
+ARG INSTALL_ZSH="true"
+# [Option] Upgrade OS packages to their latest versions
+ARG UPGRADE_PACKAGES="true"
+
+# Install needed packages, yarn, nvm and setup non-root user. Use a separate RUN statement to add your own dependencies.
+ARG USERNAME=node
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+ARG NPM_GLOBAL=/usr/local/share/npm-global
+ENV NVM_DIR=/usr/local/share/nvm
+ENV NVM_SYMLINK_CURRENT=true \ 
+    PATH=${NPM_GLOBAL}/bin:${NVM_DIR}/current/bin:${PATH}
+COPY library-scripts/*.sh library-scripts/*.env /tmp/library-scripts/
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+    # Remove imagemagick due to https://security-tracker.debian.org/tracker/CVE-2019-10131
+    && apt-get purge -y imagemagick imagemagick-6-common \
+    # Install common packages, non-root user, update yarn and install nvm
+    && bash /tmp/library-scripts/common-debian.sh "${INSTALL_ZSH}" "${USERNAME}" "${USER_UID}" "${USER_GID}" "${UPGRADE_PACKAGES}" "true" "true" \
+    # Install yarn, nvm
+    && rm -rf /opt/yarn-* /usr/local/bin/yarn /usr/local/bin/yarnpkg \
+    && bash /tmp/library-scripts/node-debian.sh "${NVM_DIR}" "none" "${USERNAME}" \
+    # Configure global npm install location, use group to adapt to UID/GID changes
+    && if ! cat /etc/group | grep -e "^npm:" > /dev/null 2>&1; then groupadd -r npm; fi \
+    && usermod -a -G npm ${USERNAME} \
+    && umask 0002 \
+    && mkdir -p ${NPM_GLOBAL} \
+    && touch /usr/local/etc/npmrc \
+    && chown ${USERNAME}:npm ${NPM_GLOBAL} /usr/local/etc/npmrc \
+    && chmod g+s ${NPM_GLOBAL} \
+    && npm config -g set prefix ${NPM_GLOBAL} \
+    && sudo -u ${USERNAME} npm config -g set prefix ${NPM_GLOBAL} \
+    # Install eslint
+    && su ${USERNAME} -c "umask 0002 && npm install -g eslint" \
+    && npm cache clean --force > /dev/null 2>&1 \
+    # Install python-is-python3 on bullseye to prevent node-gyp regressions
+    && . /etc/os-release \
+    && if [ "${VERSION_CODENAME}" = "bullseye" ]; then apt-get -y install --no-install-recommends python-is-python3; fi \
+    # Clean up
+    && apt-get autoremove -y && apt-get clean -y && rm -rf /var/lib/apt/lists/* /root/.gnupg /tmp/library-scripts
+
+# [Optional] Uncomment this section to install additional OS packages.
+# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
+#     && apt-get -y install --no-install-recommends <your-package-list-here>
+
+# [Optional] Uncomment if you want to install an additional version of node using nvm
+# ARG EXTRA_NODE_VERSION=10
+# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"
+
+# [Optional] Uncomment if you want to install more global node modules
+# RUN su node -c "npm install -g <your-package-list-here>""

.devcontainer/devcontainer.json

@@ -0,0 +1,51 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.241.1/containers/javascript-node
+{
+  "name": "Node.js",
+  "build": {
+    "dockerfile": "Dockerfile",
+    // Update 'VARIANT' to pick a Node version: 18, 16, 14.
+    // Append -bullseye or -buster to pin to an OS version.
+    // Use -bullseye variants on local arm64/Apple Silicon.
+    "args": { "VARIANT": "16-bullseye" }
+  },
+
+  // Configure tool-specific properties.
+  "customizations": {
+    // Configure properties specific to VS Code.
+    "vscode": {
+      // Add the IDs of extensions you want installed when the container is created.
+      "extensions": [
+        "eamodio.gitlens",
+        "yzhang.markdown-all-in-one",
+        "philipbe.theme-gray-matter",
+        "bierner.markdown-preview-github-styles",
+        "xabikos.JavaScriptSnippets",
+        "dbaeumer.vscode-eslint",
+        "drKnoxy.eslint-disable-snippets",
+        "esbenp.prettier-vscode",
+        "stylelint.vscode-stylelint",
+        "jock.svg",
+        "gencer.html-slim-scss-css-class-completion",
+        "syler.sass-indented",
+        "christian-kohler.path-intellisense"
+      ]
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally.
+  "forwardPorts": [3000],
+
+  // Use 'postCreateCommand' to run commands after the container is created.
+  "postCreateCommand": "yarn && yarn prepare-data",
+  "postStartCommand": "echo 'Please read the README document at https://github.com/apache/apisix-website before using, developing, or encountering problems.'",
+
+  // Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+  "remoteUser": "node",
+  "features": {
+    "git": "os-provided"
+  },
+  "hostRequirements": {
+    "memory": "2gb"
+  }
+}

README.md

@@ -13,15 +13,13 @@ A cloud-native microservices API Gateway
 
 <br>
 
-## Usage
+## Getting Started
 
 > If you want to write a blog or fix some blog-related issues, please read [Apache APISIX Blog Contributing Guide](http://apisix.apache.org/docs/general/blog) first.
 
 ### Pre-requisites
 
-First, you need to install `Node.js`, `Yarn`, `Git`.
-
-Since the installation method may change, we recommend that you check the installation method on the corresponding official website. If you encounter any problems, please feel free to create an issue.
+First, you need to install **Git**.
 
 Then you should fork this repo, and clone your fork:
 
@@ -36,21 +34,41 @@ git remote add upstream https://github.com/apache/apisix-website.git
 cd apisix-website
 ```
 
-### Basic
+### Getting started in a Dev Container
+
+If you are using **VS Code**, **Docker**, and **Remote - Containers** plugin, you can use this to get started quickly.
+
+> No, but want to try this way? Please read [Developing inside a Container#Installation](https://code.visualstudio.com/docs/remote/containers#_installation).
+
+Then, start **VS Code**, run the `Remote-Containers: Open Folder in Container...` command.
+
+> **Tip:** For details on how to do this, see the documentation [Developing inside a Container#Quick Start](https://code.visualstudio.com/docs/remote/containers#_quick-start-open-an-existing-folder-in-a-container).
+
+After the initialization, you can skip the preparation part of the commands below and read [the rest](#previewing-documents-developing) directly.
+
+### Getting started in the conventional way
+
+First, you need to install **Node.js**, **Yarn**.
+
+> **Tip:** Since the installation method may change, we recommend that you check the installation method on the corresponding official website. If you encounter any problems, please feel free to create an issue.
+
+Then you can read [the commands](#commands) below.
+
+## Commands
 
 When you find that some commands do not run, or cannot be found, look at the package.json file.
 
-This may be because the project is being updated quickly, but there is no time to make updates to the relevant documentation.
+This may be because the project is being updated quickly, but the corresponding developer did not find the time to update the corresponding documentation.
 
-#### Preparation
+### Preparation
 
 Except for the following commands that you need to run after downloading the project for the first time, you can **try running them again** when you encounter any problems.
 
 ```sh
 # 1. Install deps
 yarn
 
-# 2. Prepare necessory data
+# 2. Prepare necessary data
 yarn prepare-data
 
 # Tip.
@@ -61,7 +79,15 @@ yarn generate-repos-info # Generate repository information for each project
 yarn generate-picked-posts # Generate frontmatter information for featured blogs
 ```
 
-#### Preview documentation, Development
+> If you get a 403 error `Rate Limit Exceeded` from GitHub, that means you have hit the GitHub API rate limit. the project needs your [personal access token](https://github.com/settings/tokens) to unlimit it.
+>
+> If you don't already have one, [create one](https://github.com/settings/tokens/new), and run below command in your terminal (no scope to your personal data is needed)
+>
+> ```bash
+> export GITHUB_TOKEN=${your token}
+> ```
+
+### Previewing documents, Developing
 
 When you modify a document, blog, or page code, the preview in development mode is the fastest.
 
@@ -86,7 +112,7 @@ yarn start:blog:zh
 yarn start:website
 ```
 
-#### Build locally
+### Building
 
 When you want to build or preview a site that looks the same as it does online, run the following commands.
 
@@ -111,13 +137,13 @@ preview=true yarn build:website && yarn serve:website
 
 Next, you can modify the documentation or code, commit it and push it to GitHub when you're done. If you're not familiar with this, you can read [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) first.
 
-### Advance
+## Advance Guide
 
 If you only want to modify the `*.md` files, the above guide may be sufficient.
 
 But if you need to develop, please read the guide below.
 
-#### Project Structure
+### Project Structure
 
 Omitted some documents that may not be important.