docs: refactor installation

Signed-off-by: Bird <aflybird0@gmail.com> docs: refactor installation Signed-off-by: Bird <aflybird0@gmail.com> docs: refactor installation Signed-off-by: Bird <aflybird0@gmail.com>
devstream-io · Oct 9, 2022 · 3eabc53 · 3eabc53
1 parent f56c8b7
commit 3eabc53
Show file tree

Hide file tree

Showing 11 changed files with 156 additions and 165 deletions.
diff --git a/docs/best-practices/gitops.md b/docs/best-practices/gitops.md
@@ -32,18 +32,24 @@ Note: These dependencies are optional; you can use dependency to make sure a cer
 
 ## 1 Download DevStream (`dtm`)
 
-Download the appropriate `dtm` version for your platform from [DevStream Releases](https://github.com/devstream-io/devstream/releases).
+In your working directory, run:
 
-> Remember to rename the binary file to `dtm` so that it's easier to use. For example: `mv dtm-darwin-arm64 dtm`.
+```shell
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/install/download.sh)"
+```
+
+This will download the corresponding `dtm` binary to your working directory according to your OS and chip architecture, and grant the binary execution permission.
 
-> Once downloaded, you can run the binary from anywhere. Ideally, you want to put it in a place that is in your PATH (e.g., `/usr/local/bin`).
+> Optional: you can then move `dtm` to a place which is in your PATH. For example: `mv dtm /usr/local/bin/`.
+
+_For more details on how to install, see [install dtm](../install.md)._
 
 ## 2 Prepare the Config File
 
-Download the `gitops.yaml` to your working directory:
+Run the following command to generate a template configuration file for gitops `gitops.yaml`.
 
-```bash
-curl -o gitops.yaml https://raw.githubusercontent.com/devstream-io/devstream/main/examples/gitops.yaml
+```shell
+./dtm show config -t gitops > gitops.yaml
 ```
 
 Then modify the `gitops.yaml` file accordingly.

diff --git a/docs/best-practices/gitops.zh.md b/docs/best-practices/gitops.zh.md
@@ -22,23 +22,29 @@
 
 **注意**：依赖并不是必须指定的，我们可以用依赖确保某个工具可以先于另外一个工具安装。我们应该根据实际的使用场景来使用`dependsOn`。
 
-## 1 下载DevStream（`dtm`）
+## 1 下载 DevStream（`dtm`）
 
-在[DevStream Releases](https://github.com/devstream-io/devstream/releases)页面下载适合你操作系统和CPU架构的`dtm`。
+进入你的工作目录，运行：
 
-> 将二进制文件改名为`dtm`，以便易于使用。例如，执行：`mv dtm-drawin-arm64 dtm`。
+```shell
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/install/download.sh)"
+```
+
+这个命令会根据你的操作系统和芯片架构下载对应的 `dtm` 二进制文件到你的工作目录中，并赋予二进制文件执行权限。
+
+> 可选：建议你将 dtm 移动到包含于 PATH 的目录下，比如 `mv dtm /usr/local/bin/`。
 
-> 下载之后，你可以在任意地方执行这个二进制文件。你可以将它加入到你的PATH中（例如`/usr/local/bin`）。
+_更多安装方式详见[安装dtm](../install.zh.md)。_
 
 ## 2 准备配置文件
 
-将`gitops.yaml`下载到你的工作目录下：
+运行以下命令来生成 gitops 的模板配置文件 `gitops.yaml` 。
 
 ```shell
-curl -o gitops.yaml https://raw.githubusercontent.com/devstream-io/devstream/main/examples/gitops.yaml
+./dtm show config -t gitops > gitops.yaml
 ```
 
-然后对`gitops.yaml`文件做相应的修改。
+然后对 `gitops.yaml` 文件做相应的修改。
 
 配置文件中用到的变量的解释和示例值如下：
 

diff --git a/docs/commands/install.md b/docs/commands/install.md
diff --git a/docs/commands/install.zh.md b/docs/commands/install.zh.md
diff --git a/docs/install.md b/docs/install.md
@@ -0,0 +1,51 @@
+# Installation
+
+## 0 Currently supported operating systems and chip architectures
+
+* Darwin/arm64
+* Darwin/amd64
+* Linux/amd64
+
+## 1 Install dtm binary with script
+
+In your working directory, run:
+
+```shell
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/install/download.sh)"
+```
+
+This will download the corresponding `dtm` binary to your working directory according to your OS and chip architecture, and grant the binary execution permission.
+
+> Optional: you can then move `dtm` to a place which is in your PATH. For example: `mv dtm /usr/local/bin/`.
+
+## 2 Install with [asdf](https://asdf-vm.com/)
+
+```shell
+# Plugin
+asdf plugin add dtm
+# Show all installable versions
+asdf list-all dtm
+# Install specific version
+asdf install dtm latest
+# Set a version globally (on your ~/.tool-versions file)
+asdf global dtm latest
+# Now dtm commands are available
+dtm --help
+```
+
+## 3 Download manually from the Release page
+
+You could find the latest version of `dtm` on the [Release](https://github.com/devstream-io/devstream/releases/) page and click Download.
+Note that there are multiple versions of `dtm` available, so you will need to choose the correct version for your operating system and chip architecture. Once downloaded locally, you can choose to rename it, move it to the directory containing `$PATH` and give it executable permissions, for example, on Linux you can do this by running the following command.
+
+```shell
+mv dtm-linux-amd64 /usr/local/bin/dtm
+chmod +x dtm
+```
+
+Then you can verify that the permissions and version of dtm are correct with the following command.
+
+```shell
+$ dtm version
+0.9.1
+```
diff --git a/docs/install.zh.md b/docs/install.zh.md
@@ -0,0 +1,51 @@
+# 安装
+
+## 0 当前支持的操作系统与芯片架构
+
+*  Darwin/arm64
+*  Darwin/amd64
+*  Linux/amd64
+
+## 1 用脚本安装
+
+进入你的工作目录，运行：
+
+```shell
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/install/download.sh)"
+```
+
+这个命令会根据你的操作系统和芯片架构下载对应的 `dtm` 二进制文件到你的工作目录中，并赋予二进制文件执行权限。
+
+> 可选：建议你将 dtm 移动到包含于 PATH 的目录下，比如 `mv dtm /usr/local/bin/`。
+
+## 2 用 [asdf](https://asdf-vm.com/) 安装
+
+```shell
+# Plugin
+asdf plugin add dtm
+# Show all installable versions
+asdf list-all dtm
+# Install specific version
+asdf install dtm latest
+# Set a version globally (on your ~/.tool-versions file)
+asdf global dtm latest
+# Now dtm commands are available
+dtm --help
+```
+
+## 3 从 Release 页面手动下载
+
+在 [Release](https://github.com/devstream-io/devstream/releases/) 页面找到当前最新版本 `dtm`，然后点击下载。
+需要注意的是当前 `dtm` 提供了多个版本，你需要根据操作系统和芯片架构选择自己需要的正确版本。下载到本地后，你可以选择将其重命名，移入包含在"$PATH"的目录里并赋予其可执行权限，比如在 Linux 上你可以执行如下命令完成这些操作：
+
+```shell
+mv dtm-linux-amd64 /usr/local/bin/dtm
+chmod +x dtm
+```
+
+接着你可以通过如下命令验证 dtm 的权限以及版本等是否正确：
+
+```shell
+$ dtm version
+0.9.1
+```
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -14,15 +14,23 @@ In this quickstart, we will do the following automatically with DevStream:
 In your working directory, run:
 
 ```shell
-sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/quick-start/quickstart.sh)"
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/install/download.sh)"
 ```
 
-This will download the `dtm` binary and a `quickstart.yaml` config file to your working directory, and grant the binary execution permission.
+This will download the corresponding `dtm` binary to your working directory according to your OS and chip architecture, and grant the binary execution permission.
 
 > Optional: you can then move `dtm` to a place which is in your PATH. For example: `mv dtm /usr/local/bin/`.
 
+_For more details on how to install, see [install dtm](./install.md)._
+
 ## 2 Configuration
 
+Run the following command to generate the template configuration file `config.yaml` for quickstart.
+
+```shell
+./dtm show config -t quickstart > config.yaml
+```
+
 As aforementioned, we will handle GitHub repo scaffolding and CI workflows in GitHub Actions, so, we will need the following environment variables (env vars) to be set:
 
 - GITHUB_USER

diff --git a/docs/quickstart.zh.md b/docs/quickstart.zh.md
@@ -12,16 +12,25 @@
 ## 1 下载
 
 进入你的工作目录，运行：
+
 ```shell
-sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/quick-start/quickstart.sh)"
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/devstream-io/devstream/main/hack/install/download.sh)"
 ```
 
-这个命令会下载 `dtm` 二进制文件和 `quickstart.yaml` 的配置文件到你的工作目录中，并赋予二进制文件执行权限。
+这个命令会根据你的操作系统和芯片架构下载对应的 `dtm` 二进制文件到你的工作目录中，并赋予二进制文件执行权限。
 
 > 可选：建议你将 dtm 移动到包含于 PATH 的目录下，比如 `mv dtm /usr/local/bin/`。
 
+_更多安装方式详见[安装dtm](./install.zh.md)。_
+
 ## 2 配置
 
+运行以下命令来生成 quickstart 的模板配置文件 `config.yaml` 。
+
+```shell
+./dtm show config -t quickstart > config.yaml
+```
+
 正如前文所述，我们将在 GitHub Actions 中操作 GitHub 仓库的脚手架和 CI 工作流。所以，我们需要设置以下环境变量：
 
 - GITHUB_USER

diff --git a/hack/install/download.sh b/hack/install/download.sh
@@ -23,12 +23,17 @@ function init() {
 }
 
 function getLatestReleaseVersion() {
-  latestVersion=$(curl -s https://api.github.com/repos/devstream-io/devstream/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
+  if [ -n "${GITHUB_TOKEN}" ]; then
+    AUTH_HEADER="-H Authorization: token ${GITHUB_TOKEN}"
+  fi
+
+  # like "v1.2.3"
+  latestVersion=$(curl ${AUTH_HEADER} -s https://api.github.com/repos/devstream-io/devstream/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
   if [ -z "$latestVersion" ]; then
     echo "Failed to get latest release version"
     exit 1
   fi
-  echo "Latest dtm release version: ${latestVersion}\n"
+  echo "Latest dtm release version: ${latestVersion}"
 }
 
 function downloadDtm() {

diff --git a/hack/quick-start/quickstart.sh b/hack/quick-start/quickstart.sh