Clean up "install" section (#1213)
## Description This is the first of many changes to improve the Corso documentation. This page will see more edits with the possibility of further consolidaiton. The issues this and subsequent comments are trying to fix include: - Complexity - Too many clicks - Information spread out across too many pages - No single-page getting started guide - Incorrect or stale information ## Type of change <!--- Please check the type of change your PR introduces: ---> - [x] 🗺️ Documentation ## Test Plan - [x] 💪 Manual
This commit is contained in:
Niraj Tolia
GitHub
parent
2a51cc6975
commit
fc218457d7
@ -55,7 +55,7 @@ Before setting you your Corso S3 repository, the following prerequisites must be
|
||||
|
||||
### Credential setup {#s3-creds-setup}
|
||||
|
||||
Corso supports the credential options offered by the Go SDK. For Full details, see the *Specifying Credentials*
|
||||
Corso supports the credential options offered by the AWS Go SDK. For Full details, see the *Specifying Credentials*
|
||||
section of the [official documentation](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html).
|
||||
|
||||
* **Environment variables** - set and export `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. If using temporary
|
||||
|
||||
@ -1,83 +0,0 @@
|
||||
# Installation
|
||||
|
||||
Corso releases are available using the following options:
|
||||
|
||||
import TOCInline from '@theme/TOCInline';
|
||||
|
||||
<TOCInline toc={toc} maxHeadingLevel={2}/><br/>
|
||||
|
||||
:::note
|
||||
|
||||
To maximize portability across platforms, Corso is available as a container image. In the future,
|
||||
releases may also be available as operating system specific pre-built binaries.
|
||||
|
||||
In the meantime, if you want to run Corso as a binary, refer to the
|
||||
[instructions on how to build from source](developers/build).
|
||||
|
||||
:::
|
||||
|
||||
## Docker image
|
||||
|
||||
To use Corso as a Docker image, you need to have [Docker installed](https://docs.docker.com/engine/install/)
|
||||
on your machine.
|
||||
|
||||
### Docker command
|
||||
|
||||
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 directory for logs, if enabled.
|
||||
|
||||
To create the environment variables file, you can run the following.
|
||||
|
||||
```bash
|
||||
# create an env vars file
|
||||
$ cat <<EOF ~/.corso/corso.env
|
||||
CORSO_PASSPHRASE
|
||||
AZURE_TENANT_ID
|
||||
AZURE_CLIENT_ID
|
||||
AZURE_CLIENT_SECRET
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
AWS_SESSION_TOKEN
|
||||
EOF
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
Depending on your preferred method for passing AWS credentials, you may need to adapt the `AWS_` variables in the file.
|
||||
See [AWS Credentials Setup](/configuration/repos##s3-creds-setup) for more details.
|
||||
|
||||
:::
|
||||
|
||||
The following command will list the Corso Exchange backups. You can adapt the folder mappings, container tag, and the command
|
||||
as needed.
|
||||
|
||||
```bash
|
||||
$ docker run --env-file ~/.corso/corso.env \
|
||||
-v ~/.corso/corso:/app/corso \
|
||||
corso/corso backup list exchange
|
||||
```
|
||||
|
||||
### Available variants
|
||||
|
||||
The Corso image is available on DockerHub for the following architectures:
|
||||
|
||||
* Linux and Windows x86-64 - `amd64`
|
||||
* ARM 64-bit - `arm64`
|
||||
|
||||
:::tip
|
||||
|
||||
For Windows, you can run the `amd64` container in
|
||||
[Linux Mode](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux)
|
||||
|
||||
:::
|
||||
|
||||
The following tags are available:
|
||||
|
||||
* `:x.y.z` - A specific release build
|
||||
* `:pre-release` - The most recent pre-release if newer that the latest stable release
|
||||
* `:nightly` - The most recent unstable developer build
|
||||
* `:SHA` - A specific build
|
||||
@ -12,5 +12,5 @@ beyond M365, will expand based on the interest and needs of the community.
|
||||
|
||||
## Getting started
|
||||
|
||||
Follow the instructions in the [Installation](/install) and [Initial Configuration](/configuration/concepts) sections to
|
||||
Follow the instructions in the [Running Corso](/running) and [Initial Configuration](/configuration/concepts) sections to
|
||||
setup Corso and get it ready for first use. You can then go through the [Tutorial](/tutorial) section to see it in action.
|
||||
|
||||
67
docs/docs/running.md
Normal file
67
docs/docs/running.md
Normal file
@ -0,0 +1,67 @@
|
||||
# Running Corso
|
||||
|
||||
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 OS X.
|
||||
|
||||
:::note
|
||||
|
||||
We highly recommend the use of Corso's Docker container when getting started. For Windows, you can run the `amd64`
|
||||
container in [Linux Mode](https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/quick-start-windows-10-linux).
|
||||
|
||||
While our documentation focuses on the Docker command-line, converting the examples to work with native executables
|
||||
should be straightforward.
|
||||
|
||||
:::
|
||||
|
||||
As shown in the following example command and described further below, two things are needed to run Corso commands in
|
||||
its Docker container:
|
||||
|
||||
* Environment variables containing configuration information
|
||||
* A local directory (a `volume` in Docker terminology) for Corso to store configuration and logs
|
||||
|
||||
```bash
|
||||
$ docker run --env-file ~/.corso/corso.env \
|
||||
--volume ~/.corso/corso:/app/corso \
|
||||
corso/corso <command> <command options>
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Three distinct pieces of configuration are required by Corso:
|
||||
|
||||
* S3 object storage configuration to store backups. See [AWS Credentials Setup](/configuration/repos##s3-creds-setup) for
|
||||
alternate ways to pass AWS credentials.
|
||||
* `AWS_ACCESS_KEY_ID`:
|
||||
* `AWS_SECRET_ACCESS_KEY`:
|
||||
* (Optional) `AWS_SESSION_TOKEN`:
|
||||
|
||||
* Microsoft 365 Configuration
|
||||
* `AZURE_TENANT_ID`:
|
||||
* `AZURE_CLIENT_ID`:
|
||||
* `AZURE_CLIENT_SECRET`:
|
||||
|
||||
* Corso Security Passphrase
|
||||
* `CORSO_PASSPHRASE`:
|
||||
|
||||
For ease of use with Docker, we recommend adding the names of the required environment variables (but not their
|
||||
values!) to a [Docker environment variables file](https://docs.docker.com/engine/reference/commandline/run/#set-environment-variables--e---env---env-file).
|
||||
To create the environment variables file, you can run the following command:
|
||||
|
||||
```bash
|
||||
# create an env vars file
|
||||
$ cat <<EOF ~/.corso/corso.env
|
||||
CORSO_PASSPHRASE
|
||||
AZURE_TENANT_ID
|
||||
AZURE_CLIENT_ID
|
||||
AZURE_CLIENT_SECRET
|
||||
AWS_ACCESS_KEY_ID
|
||||
AWS_SECRET_ACCESS_KEY
|
||||
AWS_SESSION_TOKEN
|
||||
EOF
|
||||
```
|
||||
|
||||
## Local directory
|
||||
|
||||
To preserve configuration across container runs and for logs, if enabled, Corso requires access to a directory outside
|
||||
of its Docker container to read or create its configuration file (`corso.toml`). This directory is mapped by Docker to
|
||||
the `/app/corso` directory within the container.
|
||||
@ -5,7 +5,6 @@ In this tutorial you will perform your first backup followed by a restore.
|
||||
## Prerequisites
|
||||
|
||||
* 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))
|
||||
|
||||
|
||||
@ -16,7 +16,7 @@ const sidebars = {
|
||||
// By default, Docusaurus generates a sidebar from the docs folder structure
|
||||
docsSidebar: [
|
||||
'intro',
|
||||
'install',
|
||||
'running',
|
||||
'tutorial',
|
||||
{
|
||||
type: 'category',
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user