From 245bb6e73e16b4b7e010546cea2c17bbe8871afb Mon Sep 17 00:00:00 2001 From: Niraj Tolia Date: Tue, 30 Aug 2022 17:23:42 -0700 Subject: [PATCH] Misc doc changes (#667) * Bounce package.json verison to 0.1.0 * Docs cleanup driven by Vale * Clarifying language * Clarify that permissions bit is important * End of line white space linter warnings * Straighten what seemed like awkward constructs in prerequisites * Sync up with `docs/intro.md` Co-authored-by: Georgi Matev --- README.md | 8 ++++---- docs/docs/configuration/concepts.md | 4 ++-- docs/docs/configuration/m365_access.md | 20 ++++++++++---------- docs/docs/configuration/repos.md | 2 +- docs/docs/install.md | 2 +- docs/docs/intro.md | 6 +++--- docs/docs/tutorial.md | 21 +++++++++++---------- docs/package.json | 2 +- 8 files changed, 33 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 3356dbdfd..ba3500072 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Corso Corso is the first open-source tool that aims to assist IT admins with the critical task of protecting their -Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where backup -data is stored and have the flexibility to perform backups of their desired service through an intuitive interface. +Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where to store +the backup data and have the flexibility to perform backups of their desired service through an intuitive interface. As Corso evolves, it can become a great building block for more complex data protection workflows. -Corso supports supports M365 Exchange, OneDrive, SharePoint, and Teams. Coverage for additional services, possibly -even beyond M365, will expand based on the interest and needs of the community. +Corso supports M365 Exchange, OneDrive, SharePoint, and Teams. Coverage for more services, possibly +beyond M365, will expand based on the interest and needs of the community. ## Getting Started diff --git a/docs/docs/configuration/concepts.md b/docs/docs/configuration/concepts.md index 1a8fd6687..b13843a58 100644 --- a/docs/docs/configuration/concepts.md +++ b/docs/docs/configuration/concepts.md @@ -23,5 +23,5 @@ application to connect to your *M365 tenant* and transfer data during backup and * **Repository** refers to the storage location where Corso securely and efficiently stores encrypted *backups* of your *M365 Services* data. See [Repositories](/configuration/repos) for more information. -* **Backup** is a copy of your *M365 Services* data that can be restored if the original data is deleted, lost, or -corrupted. Corso performs backups incrementally; each backup only captures data that has changed between backup iterations. +* **Backup** is a copy of your *M365 Services* data to be used for restores in case of deletion, loss, or corruption of the +original data. Corso performs backups incrementall, and each backup only captures data that has changed between backup iterations. diff --git a/docs/docs/configuration/m365_access.md b/docs/docs/configuration/m365_access.md index ab51b1bf4..5a8f7f7fe 100644 --- a/docs/docs/configuration/m365_access.md +++ b/docs/docs/configuration/m365_access.md @@ -1,13 +1,13 @@ --- -description: "Connect to M365 Tenant" +description: "Connect to a Microsft 365 tenant" --- -# M365 access +# Microsoft 365 access To perform backup and restore operations, Corso requires access to your [M365 tenant](/concepts#m365-concepts) -through a properly configured [Azure AD application](/concepts#m365-concepts). +through an [Azure AD application](/concepts#m365-concepts) with appropriate permissions. -## Create Azure AD application +## Create an Azure AD application For the official documentation for adding an Azure AD Application and Service Principal using the Azure Portal see [here](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal). @@ -35,7 +35,7 @@ The following steps outline a simplified procedure for creating an Azure Ad appl The required permissions are as follows: - **TODO: Complete list of permissions** + **TODO: Complete list of permissions** | API / Permissions Name | Type | |--|--| @@ -48,12 +48,13 @@ The following steps outline a simplified procedure for creating an Azure Ad appl ## Export application credentials -Now that the Corso Azure AD application is configured, you need to capture as environment variables the information that -Corso will need to connect to the application. +After configuring the Corso Azure AD application, store the information needed by Corso to connect to the application +as environment variables. ### Tenant ID and client ID -To obtain these, select Overview from the app management panel and export the corresponding 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= @@ -68,8 +69,7 @@ Lastly, you need to configure a client secret associated with the app using **Ce 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's only available after creation. In the end, export the secret value as an environment -variable. +value right away because it won't be available later and export it as an environment variable. ```bash export AZURE_CLIENT_SECRET= diff --git a/docs/docs/configuration/repos.md b/docs/docs/configuration/repos.md index af3023016..04b7ab051 100644 --- a/docs/docs/configuration/repos.md +++ b/docs/docs/configuration/repos.md @@ -59,7 +59,7 @@ section of the [official documentation](https://docs.aws.amazon.com/sdk-for-go/v * **Environment variables** - set and export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. If using temporary credentials derived by assuming an IAM Role, you will also need `AWS_SESSION_TOKEN`. -* **Credentials file** - ensure that the credentials file is available to Corso (for example, may need to map it if +* **Credentials file** - ensure that the credentials file is available to Corso (for example, may need to map it if using Corso as a container). You may also want to set and export `AWS_PROFILE`, if not using the default profile, and `AWS_SHARED_CREDENTIALS_FILE`, if not using the default file location. You can learn more about the AWS CLI environment variables [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html). diff --git a/docs/docs/install.md b/docs/docs/install.md index fbc4278fe..007223d93 100644 --- a/docs/docs/install.md +++ b/docs/docs/install.md @@ -28,7 +28,7 @@ To run the Corso container, it's recommended that you: * Export [Corso key configuration environment variables](cli/corso_env) and add their names to an [environment variables file](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file) * Map a local directory to `/app/corso`. Corso will look for or create the `corso.toml` config file there. This will preserve - configuration across container runs. Corso will use the directoy for logs, if enabled. + configuration across container runs. Corso will use the directory for logs, if enabled. To create the environment variables file, you can run the following. diff --git a/docs/docs/intro.md b/docs/docs/intro.md index d8c51be2a..9c45bec61 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -3,11 +3,11 @@ ## Overview Corso is the first open-source tool that aims to assist IT admins with the critical task of protecting their -Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where backup -data is stored and have the flexibility to perform backups of their desired service through an intuitive interface. +Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where to store +the backup data and have the flexibility to perform backups of their desired service through an intuitive interface. As Corso evolves, it can become a great building block for more complex data protection workflows. -Corso supports supports M365 Exchange, OneDrive, SharePoint, and Teams. Coverage for additional services, possibly +Corso supports M365 Exchange, OneDrive, SharePoint, and Teams. Coverage for more services, possibly beyond M365, will expand based on the interest and needs of the community. ## Getting started diff --git a/docs/docs/tutorial.md b/docs/docs/tutorial.md index fa1fa1937..430761f86 100644 --- a/docs/docs/tutorial.md +++ b/docs/docs/tutorial.md @@ -4,9 +4,10 @@ In this tutorial you will perform your first backup followed by a restore. ## Prerequisites -* Docker is installed and Corso container is available (see [Installation](/install)) -* Corso is connected to your M365 Tenant (see [M365 Access](/configuration/m365_access)) -* Corso has initialized a backup repository (see [Repositories](/configuration/repos)) +* Install Docker +* Pull the Corso container (see [Installation](/install)) +* Configure connection to your M365 Tenant (see [M365 Access](/configuration/m365_access)) +* Initialize a Corso backup repository (see [Repositories](/configuration/repos)) ## Your first backup @@ -23,10 +24,10 @@ $ docker run -e CORSO_PASSPHRASE \ ``` :::note -Your first backup may take some time if your mailbox has many items so please be patient. +Your first backup may take some time if your mailbox is large. ::: -**TODO:** Update ^^^ after Corso output from operations is finalized. +**TODO:** Update ^^^ after the finalization of Corso output from operations. ## Restore an email @@ -42,7 +43,7 @@ $ docker run -e CORSO_PASSPHRASE \ backup list exchange --user ``` -**TODO:** Update after Corso output from operations is finalized. +**TODO:** Update ^^^ after the finalization of Corso output from operations. Select one of the available backups and search through its contents. @@ -57,8 +58,8 @@ $ docker run -e CORSO_PASSPHRASE \ --email-subject ``` -The above should give you a list of any matching emails. Note the ID of the one you would like to -use for testing restore. +The output from the executed command above should display a list of any matching emails. Note the ID +of the one to use for testing restore. When you are ready to restore, use the following command: @@ -73,6 +74,6 @@ $ docker run -e CORSO_PASSPHRASE \ --email ``` -You can now find the recovered email in a folder named "Corso_Restore_DD-MMM-YYYY_HH:MM:SS" in your mailbox. +You can now find the recovered email in a mailbox folder named `Corso_Restore_DD-MMM-YYYY_HH:MM:SS`. -You are now ready to explore the [Command Line Reference](cli) and try everything that Corso can do for you. +You are now ready to explore the [Command Line Reference](cli) and try everything that Corso can do. diff --git a/docs/package.json b/docs/package.json index a3c64bc61..2c2a43dfe 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,6 +1,6 @@ { "name": "docs", - "version": "0.0.0", + "version": "0.1.0", "private": true, "scripts": { "docusaurus": "docusaurus",