larryh/corso
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Misc doc changes (#667)

Browse Source 
* 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 <gmatev@alcion.ai>
This commit is contained in:
Niraj Tolia 2022-08-30 17:23:42 -07:00 committed by GitHub
parent d927ba1dda
commit 245bb6e73e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 33 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -1,12 +1,12 @@
# Corso # Corso
Corso is the first open-source tool that aims to assist IT admins with the critical task of protecting their 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 Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where to store
data is stored and have the flexibility to perform backups of their desired service through an intuitive interface. 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. 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
even beyond M365, will expand based on the interest and needs of the community. beyond M365, will expand based on the interest and needs of the community.
## Getting Started ## Getting Started

4
docs/docs/configuration/concepts.md
View File

@ -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 * **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. *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 * **Backup** is a copy of your *M365 Services* data to be used for restores in case of deletion, loss, or corruption of the
corrupted. Corso performs backups incrementally; each backup only captures data that has changed between backup iterations. original data. Corso performs backups incrementall, and each backup only captures data that has changed between backup iterations.

20
docs/docs/configuration/m365_access.md
View File

@ -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) 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 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). [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: The required permissions are as follows:
**TODO: Complete list of permissions** **TODO: Complete list of permissions**
| API / Permissions Name | Type | | API / Permissions Name | Type |
|--|--| |--|--|
@ -48,12 +48,13 @@ The following steps outline a simplified procedure for creating an Azure Ad appl
## Export application credentials ## Export application credentials
Now that the Corso Azure AD application is configured, you need to capture as environment variables the information that After configuring the Corso Azure AD application, store the information needed by Corso to connect to the application
Corso will need to connect to the application. as environment variables.
### Tenant ID and client ID ### 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 ```bash
export AZURE_TENANT_ID=<Directory (tenent) ID for configured app> export AZURE_TENANT_ID=<Directory (tenent) ID for configured app>
@ -68,8 +69,7 @@ Lastly, you need to configure a client secret associated with the app using **Ce
management panel. management panel.
Click **New Client Secret** and follow the instructions to create a secret. After creating the secret, copy the secret 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 value right away because it won't be available later and export it as an environment variable.
variable.
```bash ```bash
export AZURE_CLIENT_SECRET=<client secret value> export AZURE_CLIENT_SECRET=<client secret value>

2
docs/docs/configuration/repos.md
View File

@ -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 * **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 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 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 `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). environment variables [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html).

2
docs/docs/install.md
View File

@ -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 * 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) [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 * 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. To create the environment variables file, you can run the following.

6
docs/docs/intro.md
View File

@ -3,11 +3,11 @@
## Overview ## Overview
Corso is the first open-source tool that aims to assist IT admins with the critical task of protecting their 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 Microsoft 365 data. It provides a reliable, secure, and efficient data protection engine. Admins decide where to store
data is stored and have the flexibility to perform backups of their desired service through an intuitive interface. 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. 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. beyond M365, will expand based on the interest and needs of the community.
## Getting started ## Getting started

21
docs/docs/tutorial.md
View File

@ -4,9 +4,10 @@ In this tutorial you will perform your first backup followed by a restore.
## Prerequisites ## Prerequisites
* Docker is installed and Corso container is available (see [Installation](/install)) * Install Docker
* Corso is connected to your M365 Tenant (see [M365 Access](/configuration/m365_access)) * Pull the Corso container (see [Installation](/install))
* Corso has initialized a backup repository (see [Repositories](/configuration/repos)) * Configure connection to your M365 Tenant (see [M365 Access](/configuration/m365_access))
* Initialize a Corso backup repository (see [Repositories](/configuration/repos))
## Your first backup ## Your first backup
@ -23,10 +24,10 @@ $ docker run -e CORSO_PASSPHRASE \
``` ```
:::note :::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 ## Restore an email
@ -42,7 +43,7 @@ $ docker run -e CORSO_PASSPHRASE \
backup list exchange --user <your exchange email address> backup list exchange --user <your exchange email address>
``` ```
**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. Select one of the available backups and search through its contents.
@ -57,8 +58,8 @@ $ docker run -e CORSO_PASSPHRASE \
--email-subject <portion of subject of email you want to recover> --email-subject <portion of subject of email you want to recover>
``` ```
The above should give you a list of any matching emails. Note the ID of the one you would like to The output from the executed command above should display a list of any matching emails. Note the ID
use for testing restore. of the one to use for testing restore.
When you are ready to restore, use the following command: When you are ready to restore, use the following command:
@ -73,6 +74,6 @@ $ docker run -e CORSO_PASSPHRASE \
--email <id of your selected email> --email <id of your selected 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.

2
docs/package.json
View File

@ -1,6 +1,6 @@
{ {
"name": "docs", "name": "docs",
"version": "0.0.0", "version": "0.1.0",
"private": true, "private": true,
"scripts": { "scripts": {
"docusaurus": "docusaurus", "docusaurus": "docusaurus",