From f78e3ff5bd9cc2c038cb3e5063ce6aa9811bdca3 Mon Sep 17 00:00:00 2001 From: Niraj Tolia Date: Thu, 20 Oct 2022 09:59:49 -0700 Subject: [PATCH] Start filling out the quick start section (#1248) ## Description This commit also fixes a couple of other doc "bugs" and creates tab consistency. ## Type of change - [x] :sunflower: Feature - [x] :bug: Bugfix - [x] :world_map: Documentation --- docs/docs/quickstart.md | 111 +++++++++++++++++++++++++++++-- docs/docs/setup/configuration.md | 19 ++++-- docs/docs/setup/m365_access.md | 59 ++++++++++++++-- 3 files changed, 174 insertions(+), 15 deletions(-) diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index 8a57777d8..f7fd5ddd1 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -1,11 +1,114 @@ # Quick start -In this quick start guide, you will perform your first backup followed by a restore. +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TOCInline from '@theme/TOCInline'; -## Prerequisites +This quick start guide runs through the steps you can follow to create your first Microsoft 365 backup and restore: -* Configure connection to your M365 Tenant (see [M365 Access](/setup/m365_access)) -* Initialize a Corso backup repository (see [Repositories](/setup/repos)) + + +## Connecting to Microsoft 365 + +Obtaining credentials from Microsoft 365 to allow Corso to run is a moderately involved one-time operation. +Follow the instructions [here](setup/m365_access) to obtain the necessary credentials and then make them available to +Corso. + + + + + ```powershell + $Env:AZURE_CLIENT_ID = "" + $Env:AZURE_TENANT_ID = "" + $Env:AZURE_CLIENT_SECRET = "" + ``` + + + + + ```bash + export AZURE_TENANT_ID= + export AZURE_CLIENT_ID= + export AZURE_CLIENT_SECRET= + ``` + + + + + ```bash + export AZURE_TENANT_ID= + export AZURE_CLIENT_ID= + export AZURE_CLIENT_SECRET= + ``` + + + + +## Repository creation + +To create a secure backup location for Corso, we will create a bucket (`corso-test` is used as an example) in AWS S3. +The following commands assume that all configuration values from the previous step, `AWS_ACCESS_KEY_ID`, and +`AWS_SECRET_ACCESS_KEY` are available to the Corso binary or container. + + + + + ```powershell + # Create the AWS S3 Bucket + aws s3api create-bucket --bucket corso-test + ``` + + + + + ```bash + # Create the AWS S3 Bucket + aws s3api create-bucket --bucket corso-test + ``` + + + + + ```bash + # Create the AWS S3 Bucket + aws s3api create-bucket --bucket corso-test + ``` + + + + +Next, let's initialize the Corso repository using an encryption passphrase. + + + + ```powershell + # Initialize the Corso Repository + $Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE" + .\corso.exe repo init s3 --bucket corso-test + ``` + + + + + ```bash + # Initialize the Corso Repository + export CORSO_PASSPHRASE="CHANGE-ME-THIS-IS-INSECURE" + corso repo init s3 --bucket corso-test + ``` + + + + + ```bash + # Initialize the Corso Repository + export CORSO_PASSPHRASE="CHANGE-ME-THIS-IS-INSECURE" + docker run --env-file ~/.corso/corso.env \ + --volume $HOME/.corso:/app/corso corso/corso:latest \ + repo init s3 --bucket corso-test + ``` + + + ## Your first backup diff --git a/docs/docs/setup/configuration.md b/docs/docs/setup/configuration.md index 62a012996..dcc41e40f 100644 --- a/docs/docs/setup/configuration.md +++ b/docs/docs/setup/configuration.md @@ -11,7 +11,7 @@ Two things are needed to run Corso: * Environment variables containing configuration information * A directory for Corso to store its configuration file -## Environment Variables +## Environment variables Three distinct pieces of configuration are required by Corso: @@ -32,7 +32,12 @@ alternate ways to pass AWS credentials. -Ensure that all of the above environment variables are available in your Powershell environment. +Ensure that all of the above environment variables are defined in your Powershell environment. + + + + +Ensure that all of the above environment variables are defined in your shell environment. @@ -43,7 +48,7 @@ To create the environment variables file, you can run the following command: ```bash # Create an environment variables file - cat < ~/.corso/corso.env CORSO_PASSPHRASE AZURE_TENANT_ID AZURE_CLIENT_ID @@ -62,7 +67,13 @@ To create the environment variables file, you can run the following command: -By default, Corso store its configuration file (`.corso.toml`) in the directory where the binary is executed. +By default, Corso stores its configuration file (`.corso.toml`) in the root of the home directory. +The location of the configuration file can be specified using the `--config-file` option. + + + + +By default, Corso store its configuration file (`.corso.toml`) in the root of the home directory. The location of the configuration file can be specified using the `--config-file` option. diff --git a/docs/docs/setup/m365_access.md b/docs/docs/setup/m365_access.md index c955fc226..98606a4ce 100644 --- a/docs/docs/setup/m365_access.md +++ b/docs/docs/setup/m365_access.md @@ -4,6 +4,9 @@ description: "Connect to a Microsft 365 tenant" # Microsoft 365 access +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + To perform backup and restore operations, Corso requires access to your [M365 tenant](concepts#m365-concepts) through an [Azure AD application](concepts#m365-concepts) with appropriate permissions. @@ -59,10 +62,32 @@ as environment variables. To extract the tenant and client ID, select Overview from the app management panel and export the corresponding environment variables. -```bash -export AZURE_TENANT_ID= -export AZURE_CLIENT_ID= -``` + + + + ```powershell + $Env:AZURE_CLIENT_ID = "" + $Env:AZURE_TENANT_ID = "" + ``` + + + + + ```bash + export AZURE_TENANT_ID= + export AZURE_CLIENT_ID= + ``` + + + + + ```bash + export AZURE_TENANT_ID= + export AZURE_CLIENT_ID= + ``` + + + @@ -74,8 +99,28 @@ management panel. Click **New Client Secret** and follow the instructions to create a secret. After creating the secret, copy the secret value right away because it won't be available later and export it as an environment variable. -```bash -export AZURE_CLIENT_SECRET= -``` + + + + ```powershell + $Env:AZURE_CLIENT_SECRET = "" + ``` + + + + + ```bash + export AZURE_CLIENT_SECRET= + ``` + + + + + ```bash + export AZURE_CLIENT_SECRET= + ``` + + +