From e40d2c0f763a61f922d68034caf3a2b248498b23 Mon Sep 17 00:00:00 2001 From: Bibo Hao Date: Thu, 15 Feb 2024 01:21:22 +0800 Subject: [PATCH] update docs --- .github/workflows/deploy-docusaurus.yml | 4 +- QPod/docs/intro-cn.md | 50 +++++++++++++++---------- QPod/docs/intro-en.md | 29 +++++++++++--- QPod/docusaurus.config.ts | 4 +- 4 files changed, 57 insertions(+), 30 deletions(-) diff --git a/.github/workflows/deploy-docusaurus.yml b/.github/workflows/deploy-docusaurus.yml index 099ec46..cf5d549 100644 --- a/.github/workflows/deploy-docusaurus.yml +++ b/.github/workflows/deploy-docusaurus.yml @@ -12,7 +12,7 @@ jobs: - uses: actions/checkout@v4 - name: Setup Node.js - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: '21' @@ -23,7 +23,7 @@ jobs: npm run build - name: Setup Pages - uses: actions/configure-pages@v3 + uses: actions/configure-pages@v4 - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/QPod/docs/intro-cn.md b/QPod/docs/intro-cn.md index 2fb0ad3..fa0ffde 100644 --- a/QPod/docs/intro-cn.md +++ b/QPod/docs/intro-cn.md @@ -4,11 +4,11 @@ sidebar_position: 02 # QPod使用指引 -AI/数据科学的瑞士军刀——QPod提供了一站式、开箱即用、可自由定制的，基于容器的、开源AI/数据科学开发、分析工具。 - ## AI/数据科学的瑞士军刀 -QPod将常见的、最新的开放数据科学环境和工具封装成为了docker镜像，你无需进行繁琐的环境配置即可快速开始AI/数据科学的工程，同时能够方便地复现与分享您的研究工作。您可以在QPod中使用Jupyter Notebook/JupyterLab中运行Python, R, OpenJDK, NodeJS, Go, Julia, Octave等语言，QPod也包含了VS Code, R-Studio等工具。使用QPod，您可以： +AI/数据科学的瑞士军刀——QPod提供了一站式、开箱即用、可自由定制的，基于容器的、开源AI/数据科学开发、分析工具。 + +QPod将常见的、最新的开放数据科学环境和工具封装成为了容器镜像，你无需进行繁琐的环境配置即可快速开始AI/数据科学的工程，同时能够方便地复现与分享您的研究工作。您可以在QPod中使用Jupyter Notebook/JupyterLab中运行Python, R, OpenJDK, NodeJS, Go, Julia, Rust等语言，QPod也封装了VS Code, R-Studio等工具。使用QPod，您可以： - 📦 避免繁琐的环境配置、安装过程，QPod已经把常用的、最新的环境和工具封装在容器镜像中，您可以开箱即用； - 🌍 让您的工作更容易被自己/他人`复现`——QPod让科学研究和数据分析项目成为[可复现的工作流(reproducible pipelines)](https://doi.org/10.1038/d41586-018-07196-1)，这能让你更好地和同行[分享你的工作](https://doi.org/10.1038/515151a). @@ -18,7 +18,7 @@ QPod将常见的、最新的开放数据科学环境和工具封装成为了dock ## QPod包含了什么 -QPod封装、整理、维护了一些列的容器镜像，这些镜像包含了常见的开放AI/数据科学语言环境和安装包：Ptyhon, R, OpenJDK, NodeJS, Go, Julia, Octave等，同时封装了Jupyter Notebook / JupyterLab / VS Code / RStudio等IDE让用户便捷地进行开发、交互计算。QPod适用于下面的应用场景： +QPod封装、整理、维护了一些列的容器镜像，这些镜像包含了常见的开放AI/数据科学语言环境和安装包：Ptyhon, R, OpenJDK, NodeJS, Go, Julia, Rust等，同时封装了Jupyter Notebook / JupyterLab / VS Code / RStudio等IDE让用户便捷地进行开发、交互计算。QPod适用于下面的应用场景： - 单机使用：在笔记本/台式机/工作站上使用，作为AI/数据科学开发环境； - 多租户使用：在服务器/集群上供多用户使用，以共享服务器计算资源（如GPU）； @@ -26,17 +26,31 @@ QPod封装、整理、维护了一些列的容器镜像，这些镜像包含了 ## 安装使用 `1-2-3-GO`🎉 -### 0.安装Docker +### 0. 在服务器/笔记本上安装Docker + +- Linux (如: 最新版Ubuntu LTS): 直接安装 [docker-ce](https://hub.docker.com/search/?offering=community&type=edition&operating_system=linux) ( 社区版、免费 ) directly (也可以使用其他容器平台，例如podman)； + +- macOS: 直接安装 [docker-ce-desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac)； + +- Windows (>=10): + + - 选项1 (推荐): 先启用WSL2并安装最新的Ubuntu发行, 再参照在Linux上安装[docker-ce](https://hub.docker.com/search/?offering=community&type=edition&operating_system=linux)的步骤即可； + - Option 2: 直接安装[docker-ce desktop](https://desktop.docker.com/win/stable/amd64/Docker%20Desktop%20Installer.exe)。 -Linux (e.g.: Ubuntu LTS) / Windows (>=10) / macOS. +#### GPU和cuda使用的特别提示 -- CPU用户：请安装 docker-ce ( [Linux](https://hub.docker.com/search/?offering=community&type=edition&operating_system=linux) | [macOS](https://download.docker.com/mac/stable/Docker.dmg) | [Windows](https://download.docker.com/win/stable/Docker%20for%20Windows%20Installer.exe) ) 或 [docker-ee](https://hub.docker.com/search/?offering=enterprise&type=edition) -- GPU用户：需使用Linux，在安装Docker之后还需安装[NVIDIA driver](https://github.com/NVIDIA/nvidia-docker/wiki/Frequently-Asked-Questions#how-do-i-install-the-nvidia-driver)与最新版的[nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-docker#quickstart) +**请安装docker-ce，直接使用yum/apt官方源安装的docker有可能不能搭配cuda使用。** + +在安装Docker之后还需安装下面两个组件： + +- 与硬件设备适配的最新[NVIDIA driver](https://github.com/NVIDIA/nvidia-docker/wiki/Frequently-Asked-Questions#how-do-i-install-the-nvidia-driver) +- 与最新版的[nvidia-container-toolkit](https://github.com/NVIDIA/nvidia-docker#quickstart) ### 1.选择你需要的功能包和你的工作目录 -- 从项目主页底部的表格（QPod镜像功能列表）中，选择你需要的功能包，如果你的磁盘空间和网速满足要求则推荐CPU用户选择`full`，GPU用户选择`full-cuda` -- 选择你的工作目录，请使用绝对路径（如`/root`,`/User/me`,`D:/work`） +- 选择你的工作目录`WORKDIR`，请使用绝对路径（如`/root`,`/User/me`,`D:/work`）； + +- 从 [QPod镜像功能列表](tutorial-basics/qpod-stacks.md) 中，选择你需要的功能包，如果你的磁盘空间和网速满足要求则推荐CPU用户选择`full`，GPU用户选择`full-cuda`。 ### 2.准备下载和启动容器服务 @@ -100,22 +114,18 @@ timeout 10 && docker logs QPod 2>&1|findstr token= ## 附加信息 -### FAQ - -关于FAQ系列问题请参见[此处](https://github.com/QPod/docker-images/wiki) - ### 硬件 -镜像需建立在`ubuntu:latest`且只能在×86平台测试，arm64/ppc64le平台预计进行少量修改之后可以适配。 +镜像需建立在`ubuntu:latest`且只能在x86平台测试，arm64/ppc64le平台预计进行少量修改之后可以适配。 ### 安装包管理 -强烈不建议使用`conda`来安装lib或package，鉴于conda无法复用已有的系统库且无法提供稳定、最新的Liunx系统安装包库（例如某些包在`debian:jessie`下构建，在`debian:stretch`下就无法正常使用）。 +考虑到下面的原因，强烈不建议使用`conda`来安装lib或package，建议直接使用pypi： + +- conda安装源镜像在很多企业内网环境不可用（尤其是金融、医疗机构等严格隔离的内网网络），但这些机构往往有pypi源； +- conda无法复用已有的系统库且无法提供稳定、最新的Liunx系统安装包库（例如某些包在`debian:jessie`下构建，在`debian:stretch`下就无法正常使用）； +- 建立多个`conda env`环境会通过复制程序包来占用大量冗余的磁盘空间，其实可以通过使用建立多个容器实例来更好地管理和隔离不同的环境。 ### 定制化 若发现有系统库、Python模块或R包的缺失，可在`work`文件夹的`install_XX.list`中进行补充。 - -### 致谢 - -感谢[Logan](https://github.com/liuhaoge)同学的翻译和建议。 diff --git a/QPod/docs/intro-en.md b/QPod/docs/intro-en.md index edd4873..36c3683 100644 --- a/QPod/docs/intro-en.md +++ b/QPod/docs/intro-en.md @@ -6,11 +6,11 @@ sidebar_position: 01 ## Your Swiss Army Knife for AI & Data Science -In a nutshell, `QPod` ( [DockerHub](https://hub.docker.com/r/qpod/qpod/) | [GitHub](https://github.com/QPod/docker-images) ) is an **out-of-box Data Science / AI environment and platform** at your fingertip which you would love 💕. +In a nutshell, `QPod` ( [DockerHub](https://hub.docker.com/u/qpod/) | [GitHub](https://github.com/QPod/) ) is an **out-of-box Data Science / AI environment and platform** at your fingertip which you would love 💕. With Docker and `QPod`, you -- 📦 can start your data science / AI projects with nearly `zero configuration` - QPod puts everything about installing (latest) packages and configuring environment into standard docker images and set you free from these tedious work. +- 📦 can start your data science / AI projects with nearly `zero configuration` - QPod puts everything about installing (latest) packages and configuring environment into standard docker images and sets you free from these tedious work. - 🌍 will find your work more `easy-to-reproduce` - QPod standard images make scientific research or data analysis project as [reproducible pipelines](https://doi.org/10.1038/d41586-018-07196-1) and help you [share your work with others](https://doi.org/10.1038/515151a). - 🆙 can easily `scale-up and scale-out` your algorithms and key innovations - QPod help you move forward smoothly from the development stage to deployment stage by re-using these images to either to provide RESTful APIs or orchestrate map/reduce operations on big data. @@ -30,16 +30,33 @@ With Docker and `QPod`, you ## How to use? `1-2-3-GO`🎉 -### 0. Have docker installed on your laptop/server - Linux (e.g.: Ubuntu LTS) / Windows (>=10) / macOS +### 0. Have docker installed on your laptop/server -- Install **Docker >= 19.03**: `docker-ce` ( community version & free: [Linux](https://hub.docker.com/search/?offering=community&type=edition&operating_system=linux) | [macOS](https://hub.docker.com/editions/community/docker-ce-desktop-mac) | [Windows](https://desktop.docker.com/win/stable/amd64/Docker%20Desktop%20Installer.exe) ) on your laptop/server. **Docker installed from default Ubuntu/CentOS repository probably won't work for GPU!** -- If you want to use *NVIDIA GPUs* with `QPod`, Linux server or latest Windows WSL2 is **required**. After installing **Docker >= 19.03**, also install both the [`NVIDIA driver`](https://github.com/NVIDIA/nvidia-docker/wiki/Frequently-Asked-Questions#how-do-i-install-the-nvidia-driver) and the latest version of [`nvidia-container-toolkit`](https://github.com/NVIDIA/nvidia-docker#quickstart) to use the GPUs in containers. +- Linux (e.g.: Ubuntu LTS): install [docker-ce](https://hub.docker.com/search/?offering=community&type=edition&operating_system=linux) ( community version & free: ) directly (or install other container services like podman). + +- macOS: install [docker-ce-desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac) + +- Windows (>=10): + + - Option 1 (recommended): install WSL2 and latest Ubuntu distro, and then install [docker-ce](https://hub.docker.com/search/?offering=community&type=edition&operating_system=linux) just like on Linux. + - Option 2: [docker-ce desktop](https://desktop.docker.com/win/stable/amd64/Docker%20Desktop%20Installer.exe) + +### Special reminder for GPU and cuda users + +**Docker installed from default Ubuntu/CentOS repository probably won't work for GPU!** + +If you want to use *NVIDIA GPUs* with `QPod`, Linux server or latest Windows WSL2 is **required**. + +After installing **Docker >= 19.03**, also install both + +- the [`NVIDIA driver`](https://github.com/NVIDIA/nvidia-docker/wiki/Frequently-Asked-Questions#how-do-i-install-the-nvidia-driver) that fits your hardware, +- and the latest version of [`nvidia-container-toolkit`](https://github.com/NVIDIA/nvidia-docker#quickstart) to use the GPUs in containers. ### 1. Choose the features and choose a folder on your disk - Choose a folder on your laptop/server to server as the base directory (e.g.: `/root`, `/User/me`, or `D:/work`). Use an absolute path instead of relative path -- files in this folder are visible in the environment (files outside this folder are not). -- Choose an tag from the table below (e.g `full` for your laptop, or `full-cuda` for a Linux server with NVIDIA GPU), depends on what features/moduels do you want. +- Choose an tag from [QPod feature matrix](tutorial-basics/qpod-stacks.md) (e.g `full` for your laptop, or `full-cuda` for a Linux server with NVIDIA GPU), depends on what features/moduels do you want. Typically, you can choose `full` / `full-cuda` if you have enough disk space and no worry about your network speed. ### 2. Start the container diff --git a/QPod/docusaurus.config.ts b/QPod/docusaurus.config.ts index 8a6c523..b132862 100644 --- a/QPod/docusaurus.config.ts +++ b/QPod/docusaurus.config.ts @@ -38,14 +38,14 @@ const config: Config = { // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: - 'https://github.com/QPod/QPod.github.io/tree/main/QPod/docs/', + 'https://github.com/QPod/QPod.github.io/tree/main/QPod/', }, blog: { showReadingTime: true, // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: - 'https://github.com/QPod/QPod.github.io/tree/main/QPod/blog/', + 'https://github.com/QPod/QPod.github.io/tree/main/QPod/', }, theme: { customCss: './src/css/custom.css',