Skip to content

Commit

Permalink
📝 Update readme (#1579)
Browse files Browse the repository at this point in the history
  • Loading branch information
@trallard
trallard authored Dec 1, 2022
1 parent 0ffe71c commit c702b75
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 59 deletions.
132 changes: 73 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,79 +6,85 @@
</picture>
</p>

<h1 align="center"> Your open source data science platform. Built for scale, designed for collaboration. </h1>

---

| 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

- [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.**

Not sure what to choose? Check out our [Setup Initialization](docs/source/installation/setup.md) page.

## 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
Expand All @@ -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`:
Expand All @@ -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
Expand All @@ -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).

<!-- links -->
[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
Binary file removed docs/source/images/qhub-cloud_architecture.png
View file
Binary file not shown.

0 comments on commit c702b75

Please sign in to comment.