From 0a49cd03bf09f41ac5e7b917814d2f20cfb81e32 Mon Sep 17 00:00:00 2001 From: Qiyuan Gong Date: Tue, 8 Nov 2022 16:26:59 +0800 Subject: [PATCH] [PPML] Reorg Readthedoc tutorial & menu (#6476) * Change User Guide to Introduction * Add Installation * Refine toc and examples * Refine title * Add FAQs for Installation --- docs/readthedocs/source/_toc.yml | 9 +-- .../Overview/{userguide.md => devguide.md} | 0 .../source/doc/PPML/Overview/examples.rst | 4 +- .../source/doc/PPML/Overview/install.md | 70 +++++++++++++++++++ .../source/doc/PPML/Overview/misc.rst | 11 ++- docs/readthedocs/source/doc/PPML/index.rst | 4 +- 6 files changed, 85 insertions(+), 13 deletions(-) rename docs/readthedocs/source/doc/PPML/Overview/{userguide.md => devguide.md} (100%) create mode 100644 docs/readthedocs/source/doc/PPML/Overview/install.md diff --git a/docs/readthedocs/source/_toc.yml b/docs/readthedocs/source/_toc.yml index bbfeaa36..fda3bb48 100644 --- a/docs/readthedocs/source/_toc.yml +++ b/docs/readthedocs/source/_toc.yml @@ -221,29 +221,30 @@ subtrees: - entries: - file: doc/PPML/Overview/intro title: "PPML Introduction" - - file: doc/PPML/Overview/userguide - title: 'User Guide' + - file: doc/PPML/Overview/install + title: 'Installation' - file: doc/PPML/Overview/examples title: "Tutorials" subtrees: - entries: - file: doc/PPML/Overview/quicktour - file: doc/PPML/QuickStart/end-to-end + - file: doc/PPML/Overview/azure_ppml - file: doc/PPML/Overview/misc title: "Advanced Topics" subtrees: - entries: - file: doc/PPML/Overview/ppml + - file: doc/PPML/Overview/devguide - file: doc/PPML/Overview/trusted_big_data_analytics_and_ml - file: doc/PPML/Overview/trusted_fl - file: doc/PPML/QuickStart/secure_your_services + - file: doc/PPML/QuickStart/deploy_ppml_in_production - file: doc/PPML/QuickStart/install_sgx_driver - file: doc/PPML/QuickStart/deploy_intel_sgx_device_plugin_for_kubernetes - file: doc/PPML/QuickStart/trusted-serving-on-k8s-guide - file: doc/PPML/QuickStart/tpc-h_with_sparksql_on_k8s - file: doc/PPML/QuickStart/tpc-ds_with_sparksql_on_k8s - - file: doc/PPML/QuickStart/deploy_ppml_in_production - - file: doc/PPML/Overview/azure_ppml - file: doc/PPML/Overview/azure_ppml_occlum - entries: diff --git a/docs/readthedocs/source/doc/PPML/Overview/userguide.md b/docs/readthedocs/source/doc/PPML/Overview/devguide.md similarity index 100% rename from docs/readthedocs/source/doc/PPML/Overview/userguide.md rename to docs/readthedocs/source/doc/PPML/Overview/devguide.md diff --git a/docs/readthedocs/source/doc/PPML/Overview/examples.rst b/docs/readthedocs/source/doc/PPML/Overview/examples.rst index b53218f9..e5113fec 100644 --- a/docs/readthedocs/source/doc/PPML/Overview/examples.rst +++ b/docs/readthedocs/source/doc/PPML/Overview/examples.rst @@ -3,6 +3,8 @@ Tutorials & Examples * `A Hello World Example <../Overview/quicktour.html>`__ is a very simple exmaple for getting started. -* `PPML e2e Example <../QuickStart/end-to-end.html>`__ introduces the end-to-end PPML workflow using SimpleQuery as an example. +* `PPML E2E Example <../QuickStart/end-to-end.html>`__ introduces the end-to-end PPML workflow using SimpleQuery as an example. + +* `PPML E2E Example on Azure <../Overview/azure_ppml.html>`__ introduces the end-to-end PPML workflow on Azure Cloud using TPC-H as an example. * You can also find Trusted Data Analysis, Trusted ML, Trusted DL and Trusted FL examples in `more examples `__. \ No newline at end of file diff --git a/docs/readthedocs/source/doc/PPML/Overview/install.md b/docs/readthedocs/source/doc/PPML/Overview/install.md new file mode 100644 index 00000000..59949cfd --- /dev/null +++ b/docs/readthedocs/source/doc/PPML/Overview/install.md @@ -0,0 +1,70 @@ +# PPML Installation + +--- + +#### OS requirement + + +```eval_rst +.. note:: + **Hardware requirements**: + + Intel SGX: PPML's features (except Homomorphic Encryption) are mainly built upon Intel SGX. Intel SGX requires Intel CPU with SGX feature, e.g., IceLake (3rd Xeon Platform). `Check if your CPU has SGX feature `_ +``` +```eval_rst +.. note:: + **Supported OS**: + + PPML is thoroughly tested on Ubuntu (18.04/20.04), and should works fine on CentOS/Redhat 8. +``` + +#### Enable SGX for your Cluster + +```eval_rst +.. mermaid:: + + graph TD + usesgx{Use SGX?} -- Yes --> installsgx(Install SGX Driver for Node) + usesgx{Use SGX?} -- No --> he(Homomorphic Encryption) + installsgx --> installaesm(Install AESM for Node) + installaesm --> needatt{Need Attestation?} + needatt -- Yes --> installPCCS(Install PCCS for Cluster) +``` + + +##### Install SGX Driver + +Please refer to [Install SGX (Software Guard Extensions) Driver for Xeon Server](https://bigdl.readthedocs.io/en/latest/doc/PPML/QuickStart/install_sgx_driver.html). + +##### Install AESM + +```bash +echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list > /dev/null +wget -O - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | sudo apt-key add - +sudo apt update +sudo apt-get install libsgx-urts libsgx-dcap-ql libsgx-dcap-default-qpl +``` + +##### Install PCCS (for attestation) + +Please refer to [Intel® Software Guard Extensions Data Center Attestation Primitives (Intel® SGX DCAP): A Quick Install Guide](https://www.intel.com/content/www/us/en/developer/articles/guide/intel-software-guard-extensions-data-center-attestation-primitives-quick-install-guide.html) + +##### Install Kubernetes SGX Plugin (K8S only) + +Please refer to [Deploy the Intel SGX Device Plugin for Kubernetes](https://bigdl.readthedocs.io/en/latest/doc/PPML/QuickStart/deploy_intel_sgx_device_plugin_for_kubernetes.html). + + +### FAQs + +1. Is SGX supported on CentOS 6/7? +No. Please upgrade your OS if possible. + +2. Do we need Internet connection for SGX node? +No. We can use PCCS for registration and certificates downloading. Only PCCS need Internet connection. + +3. Does PCCS requires SGX? +No. PCCS can be installed on any server with Internet connection. + +4. Can we turn off attestation? +Of course. But, urnning off attestation will break integrity provided by SGX. Attestation is turned off to simplify installation for quick start. + diff --git a/docs/readthedocs/source/doc/PPML/Overview/misc.rst b/docs/readthedocs/source/doc/PPML/Overview/misc.rst index 5c861255..41e1c604 100644 --- a/docs/readthedocs/source/doc/PPML/Overview/misc.rst +++ b/docs/readthedocs/source/doc/PPML/Overview/misc.rst @@ -1,16 +1,15 @@ Advanced Topic ==================== - -* `Privacy Preserving Machine Learning (PPML) User Guide `_ +* `PPML User Guide `_ +* `Develop your own Big Data & AI applications with BigDL PPML `_ * `Trusted Big Data Analytics and ML `_ * `Trusted FL (Federated Learning) `_ * `Secure Your Services <../QuickStart/secure_your_services.html>`_ -* `Deploy PPML (Privacy Preserving Machine Learning) Applications in the Production Environment <../QuickStart/deploy_ppml_in_production.html>`_ -* `Install SGX Driver through the Installation Package <../QuickStart/install_sgx_driver.html>`_ +* `Deploy PPML Applications in the Production Environment <../QuickStart/deploy_ppml_in_production.html>`_ +* `Install SGX Driver for Xeon Server <../QuickStart/install_sgx_driver.html>`_ * `Deploy the Intel SGX Device Plugin for Kubernetes <../QuickStart/deploy_intel_sgx_device_plugin_for_kubernetes.html>`_ * `Trusted Cluster Serving with Graphene on Kubernetes <../QuickStart/trusted-serving-on-k8s-guide.html>`_ * `TPC-H with Trusted SparkSQL on Kubernetes <../QuickStart/tpc-h_with_sparksql_on_k8s.html>`_ * `TPC-DS with Trusted SparkSQL on Kubernetes <../QuickStart/tpc-ds_with_sparksql_on_k8s.html>`_ -* `Privacy Preserving Machine Learning (PPML) on Azure User Guide `_ -* `BigDL-PPML-Azure-Occlum-Example `_ \ No newline at end of file +* `PPML on Azure with Occlum `_ \ No newline at end of file diff --git a/docs/readthedocs/source/doc/PPML/index.rst b/docs/readthedocs/source/doc/PPML/index.rst index b60a5403..a8e32ccc 100644 --- a/docs/readthedocs/source/doc/PPML/index.rst +++ b/docs/readthedocs/source/doc/PPML/index.rst @@ -18,7 +18,7 @@ Protecting privacy and confidentiality is critical for large-scale data analysis +++ - :bdg-link:`Introduction <./Overview/intro.html>` | + :bdg-link:`Installation <./Overview/install.html>` | :bdg-link:`Hello World Example <./Overview/quicktour.html>` @@ -31,7 +31,7 @@ Protecting privacy and confidentiality is critical for large-scale data analysis +++ - :bdg-link:`User Guide <./Overview/userguide.html>` | + :bdg-link:`Introduction <./Overview/intro.html>` | :bdg-link:`Advanced Topics <./Overview/misc.html>`