This is an automated email from the ASF dual-hosted git repository.
guoqi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git
The following commit(s) were added to refs/heads/master by this push:
new bdd3e823ced feat: devcontainer (#1283)
bdd3e823ced is described below
commit bdd3e823ced08b417b9721400e21b1e22f776d36
Author: Young <[email protected]>
AuthorDate: Fri Aug 12 14:02:02 2022 +0800
feat: devcontainer (#1283)
---
.devcontainer/Dockerfile | 14 +++++++++++
.devcontainer/base.Dockerfile | 55 +++++++++++++++++++++++++++++++++++++++++
.devcontainer/devcontainer.json | 51 ++++++++++++++++++++++++++++++++++++++
README.md | 50 ++++++++++++++++++++++++++++---------
4 files changed, 158 insertions(+), 12 deletions(-)
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000000..2b28681164d
--- /dev/null
+++ b/.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>"
diff --git a/.devcontainer/base.Dockerfile b/.devcontainer/base.Dockerfile
new file mode 100644
index 00000000000..a3e066fd912
--- /dev/null
+++ b/.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>""
\ No newline at end of file
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000000..d7d7efa01e9
--- /dev/null
+++ b/.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"
+ }
+}
diff --git a/README.md b/README.md
index 090931ec140..721e9aa0cf7 100644
--- a/README.md
+++ b/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,13 +34,33 @@ 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.
@@ -50,7 +68,7 @@ Except for the following commands that you need to run after
downloading the pro
# 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.
