diff --git a/README.md b/README.md
index 33b8fad2f..b173b776a 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,14 @@
+ Your open source data science platform. Built for scale, designed for collaboration.
+
---
| Information | Links |
| :---------- | :-----|
-| Project | [![License](https://img.shields.io/badge/License-BSD%203--Clause-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://opensource.org/licenses/BSD-3-Clause) [![QHUb documentation](https://img.shields.io/badge/%F0%9F%93%96%20Read-the%20docs-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://docs.nebari.dev/en/stable/) [![PyPI version](https://badge.fury.io/py/nebari.svg)](https://badge.fury.io/py/nebari) |
-| Community | [![GH discussions](https://img.shields.io/badge/%F0%9F%92%AC%20-Participate%20in%20discussions-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://github.com/nebari-dev/nebari/discussions) [![Open an issue](https://img.shields.io/badge/%F0%9F%93%9D%20Open-an%20issue-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://github.com/nebari-dev/nebari/issues/new/choose) |
+| Project | [![License](https://img.shields.io/badge/License-BSD%203--Clause-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Nebari documentation](https://img.shields.io/badge/%F0%9F%93%96%20Read-the%20docs-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://docs.nebari.dev) [![PyPI](https://img.shields.io/pypi/v/nebari)](https://badge.fury.io/py/nebari) [![conda version](https://img.shields.io/conda/vn/conda-forge/nebari)]((https://anaconda.org/conda-forge/nebari)) |
+| Community | [![GH discussions](https://img.shields.io/badge/%F0%9F%92%AC%20-Participate%20in%20discussions-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://github.com/nebari-dev/nebari/discussions) [![Open an issue](https://img.shields.io/badge/%F0%9F%93%9D%20Open-an%20issue-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://github.com/nebari-dev/nebari/issues/new/choose) [![Community guidelines](https://img.shields.io/badge/🤝%20Community-guidelines-gray.svg?colorA=2D2A56&colorB=5936D9&style=flat.svg)](https://www.nebari.dev/docs/community/) |
| CI | [![Kubernetes Tests](https://github.com/nebari-dev/nebari/actions/workflows/kubernetes_test.yaml/badge.svg)](https://github.com/nebari-dev/nebari/actions/workflows/kubernetes_test.yaml) [![Tests](https://github.com/nebari-dev/nebari/actions/workflows/test.yaml/badge.svg)](https://github.com/nebari-dev/nebari/actions/workflows/test.yaml) |
## Table of contents
@@ -19,27 +21,29 @@
- [Table of contents](#table-of-contents)
- [QHub HPC](#qhub-hpc)
- [Nebari](#nebari)
- - [:cloud: Cloud Providers](#cloud-cloud-providers)
-- [:computer: Installation](#computer-installation)
+ - [Cloud Providers ☁️](#cloud-providers-️)
+- [Installation 💻](#installation-)
- [Pre-requisites](#pre-requisites)
- [Install Nebari](#install-nebari)
-- [:label: Usage](#label-usage)
-- [:question: Questions?](#question-questions)
-- [:book: Code of Conduct](#book-code-of-conduct)
-- [:gear: Installing the Development version of Nebari](#gear-installing-the-development-version-of-nebari)
-- [:raised_hands: Contributions](#raised_hands-contributions)
+- [Usage 🚀](#usage-)
+- [Contributing to Nebari 👩🏻💻](#contributing-to-nebari-)
+ - [Installing the Development version of Nebari ⚙️](#installing-the-development-version-of-nebari-️)
+ - [Questions? 🤔](#questions-)
+- [Code of Conduct 📖](#code-of-conduct-)
- [Ongoing Support](#ongoing-support)
- [License](#license)
-**⚠️ Warning ⚠️**
-
-> The project has recently been renamed from QHub to Nebari. If your deployment is is still managed by `qhub`, performing an inplace upgrade will **IRREVOCABLY BREAK** your deployment. This will cause you to lose any data stored on the platform, including but not limited to, NFS (filesystem) data, conda-store environments, Keycloak users and groups, etc. Please [backup](https://www.nebari.dev/docs/how-tos/manual-backup) your data before attempting an upgrade.
+> **⚠️ Warning ⚠️**
+> The project has recently been renamed from QHub to Nebari. If your deployment is still managed by `qhub`, performing an in place upgrade will **IRREVOCABLY BREAK** your deployment.
+> This will cause you to lose any data stored on the platform, including but not limited to, NFS (file system) data,
+> `conda-store` environments, Keycloak users and groups, etc.
+> Make sure to [back up your data before attempting an upgrade](https://www.nebari.dev/docs/how-tos/manual-backup).
Automated data science platform. From [JupyterHub](https://jupyter.org/hub "Multi-user version of the Notebook") to Cloud environments with
[Dask Gateway](https://docs.dask.org/ "Parallel computing in Python").
-Nebari is an open source tool that enables users to build and maintain cost-effective and scalable compute/data science platforms on [HPC](#nebari-hpc) or on [Kubernetes](#nebari) with
-minimal DevOps experience.
+Nebari is an open source data platform that enables users to build and maintain cost-effective and scalable compute platforms
+on [HPC](#nebari-hpc) or [Kubernetes](#nebari) with minimal DevOps overhead.
**This repository details the [Nebari](https://nebari.dev/ "Official Nebari docs") (Kubernetes) version.**
@@ -47,38 +51,40 @@ Not sure what to choose? Check out our [Setup Initialization](docs/source/instal
## QHub HPC
-Version of Nebari based on OpenHPC.
+The HPC version of Nebari is based on [OpenHPC](https://openhpc.community/).
> NOTE: The tool is currently under development. Curious? Check out the [Nebari HPC](https://github.com/Quansight/qhub-hpc) repository.
## Nebari
-The Kubernetes version of Nebari is built using [Terraform](https://www.terraform.io/), [Helm](https://helm.sh/), and
-[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions). Terraform handles the build, change, and versioning of the infrastructure. Helm helps to define, install,
-and manage [Kubernetes](https://kubernetes.io/ "Automated container deployment, scaling, and management"). GitHub Actions is used to automatically create commits when the
-configuration file (`nebari-config.yaml`) is rendered, as well as to kick off the deployment action.
+The Kubernetes version of Nebari uses [Terraform](https://www.terraform.io/), [Helm](https://helm.sh/), and
+[GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions).
-Nebari aims to abstract all these complexities for its users. Hence, it is not necessary to know any of the above mentioned technologies to have your project successfully deployed.
+- Terraform handles the build, change, and versioning of the infrastructure.
+- Helm helps to define, install, and manage [Kubernetes](https://kubernetes.io/ "Automated container deployment, scaling, and management") resources.
+- GitHub Actions is used to automatically create commits when the configuration file (`nebari-config.yaml`) is rendered,
+ as well as to kick off the deployment action.
+
+Nebari aims to abstract all these complexities for its users.
+Hence, it is not necessary to know any of the technologies mentioned above to have your project successfully deployed.
> TLDR: If you know GitHub and feel comfortable generating and using API keys, you should have all it takes to deploy and maintain your system without the need for a dedicated
> DevOps team. No need to learn Kubernetes, Terraform, or Helm.
-### :cloud: Cloud Providers
-
-Nebari offers out-of-the-box support for [Digital Ocean](https://www.digitalocean.com/), Amazon [AWS](https://aws.amazon.com/),
-[GCP](https://cloud.google.com/ "Google Cloud Provider"), and Microsoft [Azure](https://azure.microsoft.com/en-us/).
+### Cloud Providers ☁️
-![High-level illustration of Nebari architecture](docs/source/images/nebari-cloud_architecture.png)
+Nebari offers out-of-the-box support for the major public cloud providers: [Digital Ocean](https://www.digitalocean.com/),
+Amazon [AWS](https://aws.amazon.com/), [GCP](https://cloud.google.com/ "Google Cloud Provider"), and Microsoft [Azure](https://azure.microsoft.com/en-us/).
+![High-level illustration of Nebari architecture](https://raw.githubusercontent.com/nebari-dev/nebari-docs/main/docs/static/img/welcome/nebari_overview_sequence.png)
-For more details, check out the release [blog post](https://www.quansight.com/post/announcing-nebari).
-
-## :computer: Installation
+## Installation 💻
### Pre-requisites
-- Nebari is supported by macOS and Linux operating systems (Windows is **NOT** currently supported).
-- Compatible with Python 3.7+. New to Python? We recommend using [Anaconda](https://www.anaconda.com/products/individual).
-- Adoption of virtual environments ([`conda`](https://docs.conda.io/en/latest/), [`pipenv`](https://github.com/pypa/pipenv) or
+- Operating System: Currently, Nebari supports development on macOS and Linux operating systems. Windows is NOT supported.
+ However, we would welcome contributions that add and improve support for Windows.
+- You need Python >= 3.7 on your local machine or virtual environment to work on Nebari.
+- Adopting virtual environments ([`conda`](https://docs.conda.io/en/latest/), [`pipenv`](https://github.com/pypa/pipenv) or
[`venv`](https://docs.python.org/3/library/venv.html)) is also encouraged.
### Install Nebari
@@ -89,6 +95,9 @@ To install Nebari type the following commands in your command line:
```bash
conda install -c conda-forge nebari
+
+ # if you prefer using mamba
+ mamba install -c conda-forge nebari
```
- Install using `pip`:
@@ -97,7 +106,7 @@ To install Nebari type the following commands in your command line:
pip install nebari
```
-Once finished, you can check Nebari's version (and additional CLI args) by typing:
+Once finished, you can check Nebari's version (and additional CLI arguments) by typing:
```bash
nebari --help
@@ -119,54 +128,59 @@ optional arguments:
-v, --version Nebari version
```
-## :label: Usage
+## Usage 🚀
-Nebari requires the setting of environment variables to automate the deployments fully. For details on how to obtain those variables, check the
-[installation guide](docs/source/installation/installation.md) in the docs.
+Nebari requires setting multiple environment variables to automate the deployments fully.
+For details on obtaining those variables, check the [Nebari Get started documentation][docs-get-started].
Once all the necessary credentials are gathered and set as [UNIX environment variables](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/), Nebari can be
-deployed in under 20 minutes using:
-
-```bash
-nebari init ... # generates initial config file and optionally automates deployment steps
-nebari deploy ... # creates and configures the cloud infrastructure
-```
+deployed in minutes.
-## :question: Questions?
+For detailed step-by-step instructions on how to deploy Nebari, check the [Nebari documentation][docs-deploy].
-Have a look at our [FAQ](docs/source/user_guide/faq.md) to see if your query has been answered.
+## Contributing to Nebari 👩🏻💻
-We separate the queries for Nebari into:
+Thinking about contributing? Check out our [Contribution Guidelines](CONTRIBUTING.md) to get started.
-- [GitHub Discussions](https://github.com/nebari-dev/nebari/discussions) used to raise discussions about a subject, such as: "What is the recommended way to do X with Nebari?"
+### Installing the Development version of Nebari ⚙️
-- [Issues](https://github.com/nebari-dev/nebari/issues/new/choose) for queries, bug reporting, feature requests,documentation, etc.
+To install the latest developer version (unstable) use:
-> We work around the clock to make Nebari better, but sometimes your query might take a while to get a reply. We apologise in advance and ask you to please, be patient :pray:.
+```bash
+pip install git+https://github.com/nebari-dev/nebari.git
+```
-## :book: Code of Conduct
+### Questions? 🤔
-To guarantee a welcoming and friendly community, we require contributors to follow our [Code of Conduct](https://github.com/nebari-dev/.github/blob/master/CODE_OF_CONDUCT.md).
+Have a look at our [Frequently Asked Questions (FAQ)][nebari-faqs] to see if your query has been answered.
-## :gear: Installing the Development version of Nebari
+Getting help:
-To install the latest developer version (unstable) use:
+- [GitHub Discussions][gh-discussions] is our user forum. It can be used to raise discussions about a subject,
+ such as: "What is the recommended way to do _X_ with Nebari?"
+- [Issues][nebari-issues] for queries, bug reporting, feature requests, documentation, etc.
-```bash
-pip install git+https://github.com/nebari-dev/nebari.git@dev
-```
+> We work around the clock to make Nebari better, but sometimes your query might take a while to get a reply. We
+> apologize in advance and ask you to please, be patient :pray:.
-## :raised_hands: Contributions
+## Code of Conduct 📖
-Thinking about contributing? Check out our [Contribution Guidelines](https://github.com/nebari-dev/nebari/blob/main/CONTRIBUTING.md).
+To guarantee a welcoming and friendly community, we require all community members to follow our [Code of Conduct](https://github.com/Quansight/.github/blob/master/CODE_OF_CONDUCT.md).
## Ongoing Support
-The `v0.4.0` release introduced many changes that will irrevocably break your deployment if you attempt an inplace upgrade; for details see our
-[RELEASE](RELEASE.md#release-v040---march-17-2022) notes. In order to focus on the future direction of the project, we have decided as a team that we will provide **limited** support for older versions. Any new user is encouraged to use `v0.4.0` or greater.
+The `v0.4.0` release introduced many changes that will irrevocably break your deployment if you attempt an in-place upgrade; for details, see our
+[RELEASE](RELEASE.md#release-v040---march-17-2022) notes. To focus on the future direction of the project, we have decided as a team that we will provide **limited** support for older versions. Any new user is encouraged to use `v0.4.0` or greater.
-If you're using an older version of Nebari and would like professional support, please reach out to Quansight.
+If you're using an older version of Nebari and would like professional support, please get in touch with the Nebari development team.
## License
[Nebari is BSD3 licensed](LICENSE).
+
+
+[nebari-issues]: https://github.com/nebari-dev/nebari/issues
+[nebari-faqs]: https://www.nebari.dev/faq
+[gh-discussions]: https://github.com/nebari-dev/nebari/discussions
+[docs-get-started]: https://www.nebari.dev/docs/category/get-started
+[docs-deploy]: https://www.nebari.dev/docs/get-started/deploy
diff --git a/docs/source/images/qhub-cloud_architecture.png b/docs/source/images/qhub-cloud_architecture.png
deleted file mode 100644
index eee37a482..000000000
Binary files a/docs/source/images/qhub-cloud_architecture.png and /dev/null differ