Merge pull request #45 from nebari-dev/doc-36-install

[DOCS] Add Nebari installation guides and getting-started as first directions

docs/docs/getting-started/cloud-providers.mdx

@@ -0,0 +1,62 @@
+---
+title: Choosing cloud providers
+description: Guidance for selecting a deployment provider.
+---
+
+# Choosing cloud providers
+
+A selection of Nebari supported cloud providers
+
+Now that Nebari is successfully installed, we can move forward with choosing the most suitable cloud provider to help you effectively deploy and start your projects within Nebari.
+
+To deploy Nebari, each cloud provider requires fairly wide permissions to create all the necessary cloud resources, which are governed by the **`access keys`** generated by the provider. Once you have chosen your preferred cloud provider, follow the steps described in their respective How-to Guides(how-tos/overview) to stand up a Nebari deployment on their platform.
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="gcp" label="Google GCP" default>
+
+<div class="text--center">
+  <img src="/img/started-google-cloud-logo.png" width={420} />
+</div>
+
+[Google GCP](https://docs.qhub.dev/en/latest/source/installation/setup.html#google-cloud-platform) (also known as Google Cloud Platform or GCP) is a provider of computing resources for developing, deploying, and operating computing services.
+
+For more information on how to deploy Nebari on **GCP** visit [How to deploy Nebari on GCP](/how-tos/nebari-gcp).
+</TabItem>
+<TabItem value="do" label="Digital Ocean">
+
+<div class="text--center">
+  <img src="/img/started-digital-ocean-logo.png" width={420} />
+</div>
+
+[DigitalOcean](https://docs.qhub.dev/en/latest/source/installation/setup.html#digital-ocean) is a cloud hosting provider that offers cloud computing services and Infrastructure as a Service (IaaS) known for its pricing and scalability.
+
+For more information on how to deploy Nebari on **Digital Ocean** visit [How to deploy Nebari on Digital Ocean](/how-tos/nebari-do).
+</TabItem>
+<TabItem value="aws" label="Amazon AWS">
+
+<div class="text--center">
+  <img src="/img/started-amazon-web-services-logo.png" width={420} />
+</div>
+
+[Amazon Web Services (AWS)](https://docs.qhub.dev/en/latest/source/installation/setup.html#amazon-web-services-aws) is a comprehensive, evolving cloud computing platform provided by Amazon that includes a mixture of infrastructure as a service (IaaS), platform as a service (PaaS) and packaged software as a service (SaaS) offerings.
+
+For more information on how to deploy Nebari on **AWS** visit [How to deploy Nebari on AWS](/how-tos/nebari-aws).
+</TabItem>
+<TabItem value="azure" label="Azure">
+
+<div class="text--center">
+  <img src="/img/started-azure-logo.png" width={420}/>
+</div>
+
+[Microsoft Azure](https://docs.qhub.dev/en/latest/source/installation/setup.html#microsoft-azure) is Microsoft's public cloud computing platform. It provides a range of cloud services, including compute, analytics, storage and networking.
+
+For more information on how to deploy Nebari on **Azure** visit [How to deploy Nebari on Azure](/how-tos/nebari-azure).
+</TabItem>
+</Tabs>
+
+:::warning
+While all of the above cloud providers offer free-tier accounts, some of Nebari's infrastructure resources may lie outside the scope of the free-tier quotas of these accounts, and Nebari will not prompt you when these limits are exceeded. Therefore, if your intention is to try out Nebari by carrying out a quick trial installation, you should start with a [local Nebari installation](/how-tos/nebari-local) to be sure to avoid any unexpected charges.
+:::

docs/docs/getting-started/deploy.md

@@ -0,0 +1,80 @@
+---
+id: deploy
+---
+
+# Choosing a deployment platform
+
+
+Nebari can be deployed on a bare-metal server using HPC, as well as on the major public cloud provider, or on a pre-existing Kubernetes cluster. Review the options below to determine which option best suits your needs.
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="cloud" label="Cloud" default>
+
+The cloud deployment of Nebari is considered to be the default option. It enables teams to build and maintain a cost-effective and scalable compute/data science platform in the cloud, by using an [Infrastructure as Code](https://en.wikipedia.org/wiki/Infrastructure_as_code) approach that streamlines the deployment and management of data science infrastructure.
+
+If you are not sure which option to choose, a cloud installation is likely your best option. It is suitable for most use cases, especially if:
+
+- You require scalable infrastructure
+
+- You aim to have a production environment with [GitOps] enabled by default
+
+- Your team does not have specific expertise within high-performance computing hardware, Kubernetes, Docker, and/or other cloud-native or scalable compute infrastructure technologies
+
+The cloud installation is based on Kubernetes, but knowledge of Kubernetes is **NOT** required nor is in-depth knowledge about the specific provider required either. Currently, Nebari supports [Amazon AWS](/how-tos/nebari-aws.md), [DigitalOcean](/how-tos/nebari-do.md), [Google GCP](/how-tos/nebari-gcp.md), and [Azure](/how-tos/nebari-azure.md).
+
+
+For instructions on installing and deploying Nebari on a particular cloud provider, visit our [cloud providers page](/getting-started/cloud-providers) for a list of the supported cloud providers and their respective installation how-to guides.
+
+</TabItem>
+<TabItem value="hpc" label="HPC">
+
+Nebari HPC is an opinionated open source deployment of JupyterHub based on an HPC jobscheduler (e.g. Slurm). Nebari HPC is a "distribution" of these packages much like Debian and Ubuntu are distributions of Linux.
+
+:::note
+To note, Nebari HPC can be used on other distributed compute hardware, not just HPC hardware specifically. We anticipate that Nebari HPC will be used most often on HPC hardware, however.
+:::
+
+The high level goal of this distribution is to form a cohesive set of tools that enable:
+
+- Environment management via [`conda`](https://docs.conda.io/en/latest/) and [`conda-store`](https://conda-store.readthedocs.io/en/latest/)
+
+- Monitoring of compute infrastructure and services
+
+- Scalable and efficient compute via Jupyterlab and Dask
+
+- On-prem deployment of Jupyterhub without requiring deep DevOps knowledge of the Slurm/HPC and Jupyter ecosystems
+
+Nebari HPC should be your choice if:
+
+- You have highly optimized code that requires highly performant infrastructure
+
+- You have existing HPC infrastructure
+
+- You expect that your projects will not exceed the resources/capabilities of your current infrastructure
+
+For instructions on installing and deploying Nebari HPC, visit the [How to install and setup Nebari HPC on bare metal machines](/how-tos/nebari-hpc) section of the documentation.
+
+:::note
+Although it is possible to deploy Nebari HPC in the cloud, it is not generally recommended due to potentially high costs. For more information, check out the [base cost] section of the docs.
+:::
+
+
+</TabItem>
+<TabItem value="local" label="Pre-existing Kubernetes cluster">
+
+The pre-exisitng (or local) version is recommended for **testing and development** of Nebari’s components due to its simplicity. Choose the local mode if:
+
+- You already have a Kubernetes cluster [on one of the Nebari's supported cloud]providers(/started/cloud-providers)
+- You want to test your Kubernetes cluster
+- You have available local compute setup
+- You want to try out Nebari with a quick install for exploratory purposes, without setting up environment variables
+
+You should choose another installation option, likely a [cloud install](/getting-started/cloud-providers) if you are starting from scratch (you have no compute clusters already in place) and you desire to stand up a production instance of Nebari.
+
+For instructions on installing and deploying Nebari Local, please visit [How to install and setup Nebari on an existing Kubernetes infrastructure](/how-tos/nebari-local).
+
+</TabItem>
+</Tabs>

docs/docs/getting-started/installing-nebari.md

@@ -0,0 +1,56 @@
+---
+title: Installing Nebari
+description: A guide to help you install Nebari for your team.
+---
+
+# Installing Nebari
+
+
+This installation guide provides the basic instructions to install and deploy Nebari for the first time, and assumes you are is already familiar with the [Conda](https://docs.conda.io/projects/conda/en/latest/) and [Python packaging](https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-packages) ecosystems. If you are already familiar with Nebari and would like information on advanced configuration options, feel free to skip to the [advanced-settings] section.
+
+:::note
+This guide focuses on installing Nebari for cloud usage. For other alternatives, please visit [deploying options](/getting-started/deploy.md) for an overview of the available options and their respective installation steps.
+:::
+
+## Pre-requisites
+
+Nebari heavily depends on [Terraform](https://www.terraform.io/) and a Python ecosystem. The installation of the Terraform binary is built-in within the Nebari source code and it is automatically downloaded during the first execution. Currently, only `Linux` and `macOS` are supported. `Windows` is only supported through the “Windows Subsystem for Linux” (see "WSL").
+- Currently, Nebari supports Python `3.8+`
+- For more details on Terraform and its dependencies, visit the [official Terraform documentation](https://learn.hashicorp.com/tutorials/terraform/install-cli)
+- To install conda, visit the [official conda documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html), or if you prefer, visit the [mamba installation documentation](https://github.com/mamba-org/mamba#installation)
+
+## How to install Nebari
+
+There are currently two ways to install Nebari:
+
+1. You can install Nebari directly from the Python Package Index (PyPI) using `pip`. For most common architectures and platforms (`Linux x86-64` and `macOS x86-64`), `pip` will download and install the most recent version available.
+
+    ```bash
+    python3 pip install nebari
+    ```
+
+2. Nebari is also available at [conda-forge](https://anaconda.org/conda-forge/qhub) and can be installed using the `conda` package manager by running the following command:
+
+    ```bash
+    conda install nebari -c conda-forge
+    ```
+
+    if you prefer [mamba](https://github.com/mamba-org/mamba#mamba), you can use the following command:
+
+    ```bash
+    mamba install nebari
+    ```
+
+## Verify installation
+
+You can verify that Nebari is properly installed and you are able to execute the client commands by running:
+
+```bash
+nebari --help
+```
+
+![A representation of the output generated when nebari help command argument is executed, the output contains a list of the available positional arguments and usage.](/img/validate_installation.png "Nebari's help command line output").
+
+:::note Troubleshooting
+If you are unable to successfully validate the Nebari installation above, you may want to check out our [troubleshooting guide](/troubleshooting.md).
+:::

docs/docs/how-tos/domain-registry.md

@@ -0,0 +1,12 @@
+---
+id: domain-registry
+title: How to set Nebari's DNS Domain Registry
+---
+
+# Nebari domain registry setup
+
+This domain will be where your application will be exposed.
+
+Currently, Nebari's default configuration is set for CloudFlare for automatic DNS registration. If you prefer an alternate DNS provider, you'll need to change the `--dns-provider` flag from **cloudflare** to **none** on the Nebari deploy command. The deployment process will then pause when it asks for an IP address (or CNAME, if using AWS) and prompt you to provide the desired URL.
+
+Setting a DNS record heavily depends on the provider, and thus it’s not possible to provide detailed docs here on how to create a record on all the providers out there. Searching "setting a DNS record" or "setting a CNAME DNS record" on your specific provider should yield good results.