You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by gu...@apache.org on 2022/08/12 06:02:08 UTC
[apisix-website] branch master updated: feat: devcontainer (#1283)
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 <is...@outlook.com>
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.