From 20c6c70668bab61b641ffefb1694e6bf116d9799 Mon Sep 17 00:00:00 2001 From: Niraj Tolia Date: Fri, 21 Oct 2022 12:15:04 -0700 Subject: [PATCH] Misc. doc fixes (#1290) ## Description - Add missing Docker container version - Clean up some text - Some consistency tweaks - Remove stale text in the configuration section - Spell out environment variables - Fix broken link ## Type of change - [x] :bug: Bugfix - [x] :world_map: Documentation --- docs/docs/quickstart.md | 16 ++++---- docs/docs/setup/configuration.md | 66 ++++++++++++++++++++++++-------- 2 files changed, 58 insertions(+), 24 deletions(-) diff --git a/docs/docs/quickstart.md b/docs/docs/quickstart.md index 6fe009339..5a5064945 100644 --- a/docs/docs/quickstart.md +++ b/docs/docs/quickstart.md @@ -93,13 +93,13 @@ Corso binary or container. `# Create an environment variables file mkdir -p $HOME/.corso cat < $HOME/.corso/corso.env -CORSO_PASSPHRASE -AZURE_CLIENT_ID -AZURE_TENANT_ID -AZURE_CLIENT_SECRET AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN +AZURE_CLIENT_ID +AZURE_TENANT_ID +AZURE_CLIENT_SECRET +CORSO_PASSPHRASE EOF # Initialize the Corso Repository @@ -162,9 +162,8 @@ There will be progress indicators as the backup and, on completion, you should s ## Restore an email -Now, lets explore how you can restore data from one of your backups. - -You can see all Exchange backups available with the following command: +Now, lets explore how you can restore data from one of your backups. You can see all Exchange backups available with +the following command: @@ -199,6 +198,7 @@ docker run --env-file $HOME/.corso/corso.env \\ Started At ID Status Selectors 2022-10-20T18:28:53Z d8cd833a-fc63-4872-8981-de5c08e0661b Completed (0 errors) alice@contoso.com 2022-10-20T18:40:45Z 391ceeb3-b44d-4365-9a8e-8a8e1315b565 Completed (0 errors) alice@contoso.com + ... ``` Next, select one of the available backups and list all backed up emails. See @@ -243,7 +243,7 @@ of the email you would like to use for testing restore. ... ``` -When you are ready to restore the selected email, use the following command. +To restore the selected email, use the following command. diff --git a/docs/docs/setup/configuration.md b/docs/docs/setup/configuration.md index 5092a92fd..1ec5d299c 100644 --- a/docs/docs/setup/configuration.md +++ b/docs/docs/setup/configuration.md @@ -1,12 +1,11 @@ # Configuration +import CodeBlock from '@theme/CodeBlock'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +import {Version} from '@site/src/corsoEnv'; -Corso is available as a [Docker](https://docs.docker.com/engine/install/) image (Linux `x86_64` and `arm64`) and -as an `x86_64` and `arm64` executable for Windows, Linux and macOS. - -Two things are needed to run Corso: +Two things are needed to configure Corso: * Environment variables containing configuration information * A directory for Corso to store its configuration file @@ -15,7 +14,7 @@ Two things are needed to run Corso: Three distinct pieces of configuration are required by Corso: -* S3 object storage configuration to store backups. See [AWS Credentials Setup](/setup/repos##s3-creds-setup) for +* S3 object storage configuration to store backups. See [AWS Credentials Setup](/setup/repos#s3-creds-setup) for alternate ways to pass AWS credentials. * `AWS_ACCESS_KEY_ID`: Access key for an IAM user or role for accessing an S3 bucket * `AWS_SECRET_ACCESS_KEY`: Secret key associated with the access key @@ -34,11 +33,35 @@ alternate ways to pass AWS credentials. Ensure that all of the above environment variables are defined in your Powershell environment. + ```powershell + $Env:AWS_ACCESS_KEY_ID = "..." + $Env:AWS_SECRET_ACCESS_KEY = "..." + $Env:AWS_SESSION_TOKEN = "" + + $Env:AZURE_CLIENT_ID = "..." + $Env:AZURE_TENANT_ID = "..." + $Env:AZURE_CLIENT_SECRET = "..." + + $Env:CORSO_PASSPHRASE = "CHANGE-ME-THIS-IS-INSECURE" + ``` + Ensure that all of the above environment variables are defined in your shell environment. + ```bash + export AWS_ACCESS_KEY_ID=... + export AWS_SECRET_ACCESS_KEY=... + export AWS_SESSION_TOKEN=... + + export AZURE_CLIENT_ID=... + export AZURE_TENANT_ID=... + export AZURE_CLIENT_SECRET=... + + export CORSO_PASSPHRASE=CHANGE-ME-THIS-IS-INSECURE + ``` + @@ -50,14 +73,25 @@ To create the environment variables file, you can run the following command: # Create an environment variables file mkdir -p $HOME/.corso cat < $HOME/.corso/corso.env - CORSO_PASSPHRASE - AZURE_CLIENT_ID - AZURE_TENANT_ID - AZURE_CLIENT_SECRET AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN + AZURE_CLIENT_ID + AZURE_TENANT_ID + AZURE_CLIENT_SECRET + CORSO_PASSPHRASE EOF + + # Export required variables + export AWS_ACCESS_KEY_ID=... + export AWS_SECRET_ACCESS_KEY=... + export AWS_SESSION_TOKEN=... + + export AZURE_CLIENT_ID=... + export AZURE_TENANT_ID=... + export AZURE_CLIENT_SECRET=... + + export CORSO_PASSPHRASE=CHANGE-ME-THIS-IS-INSECURE ``` @@ -68,13 +102,13 @@ To create the environment variables file, you can run the following command: -By default, Corso stores its configuration file (`.corso.toml`) in the root of the home directory. +By default, Corso stores its configuration file (`.corso.toml`) in the user's home directory. The location of the configuration file can be specified using the `--config-file` option. -By default, Corso stores its configuration file (`.corso.toml`) in the root of the home directory. +By default, Corso stores its configuration file (`.corso.toml`) in the user's home directory. The location of the configuration file can be specified using the `--config-file` option. @@ -84,11 +118,11 @@ To preserve configuration across container runs, Corso requires access to a dire to read or create its configuration file (`.corso.toml`). This directory must be mapped, by Docker, to the `/app/corso` directory within the container. -```bash -$ docker run --env-file $HOME/.corso/corso.env \ - --volume $HOME/.corso/corso:/app/corso \ - ghcr.io/alcionai/corso -``` +{ +`docker run --env-file $HOME/.corso/corso.env \\ + --volume $HOME/.corso:/app/corso ghcr.io/alcionai/corso:${Version()} \\ + ` +}