From a976c9190cbd60165cd852f0fcb6398cb88501e7 Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Fri, 11 Nov 2022 12:48:52 +0100 Subject: [PATCH] Use awscli in the getting started guide --- doc/book/quick-start/_index.md | 121 +++++++++++++++++++++------------ 1 file changed, 78 insertions(+), 43 deletions(-) diff --git a/doc/book/quick-start/_index.md b/doc/book/quick-start/_index.md index 21331dcb..84317c4c 100644 --- a/doc/book/quick-start/_index.md +++ b/doc/book/quick-start/_index.md @@ -42,15 +42,16 @@ you can [build Garage from source](@/documentation/cookbook/from-source.md). ## Configuring and starting Garage -### Writing a first configuration file +### Generating a first configuration file This first configuration file should allow you to get started easily with the simplest possible Garage deployment. -**Save it as `/etc/garage.toml`.** -You can also store it somewhere else, but you will have to specify `-c path/to/garage.toml` -at each invocation of the `garage` binary (for example: `garage -c ./garage.toml server`, `garage -c ./garage.toml status`). -```toml +We will create it with the following command line +to generate unique and private secrets for security reasons: + +```bash +cat > garage.toml < \ - \ - --api S3v4 +python -m pip install --user awscli ``` -### Use `mc` - -You can not list buckets from `mc` currently. - -But the following commands and many more should work: +Now that `awscli` is installed, you must configure it to talk to your Garage instance, +with your key. There are multiple ways to do that, the simplest one is to create a file +named `~/.awsrc` with this content: ```bash -mc cp image.png my-garage/nextcloud-bucket -mc cp my-garage/nextcloud-bucket/image.png . -mc ls my-garage/nextcloud-bucket -mc mirror localdir/ my-garage/another-bucket +export AWS_ACCESS_KEY_ID=xxxx # put your Key ID here +export AWS_SECRET_ACCESS_KEY=xxxx # put your Secret key here +export AWS_DEFAULT_REGION='garage' +export AWS_ENDPOINT='http://localhost:3900' + +function aws { command aws --endpoint-url $AWS_ENDPOINT $@ ; } +aws --version ``` +Now, each time you want to use `awscli` on this target, run: + +```bash +source ~/.awsrc +``` + +*You can create multiple files with different names if you +have multiple Garage clusters or different keys. +Switching from one cluster to another is as simple as +sourcing the right file.* + +### Example usage of `awscli` + +```bash +# list buckets +aws s3 ls + +# list objects of a bucket +aws s3 ls s3://my_files + +# copy from your filesystem to garage +aws s3 cp /proc/cpuinfo s3://my_files/cpuinfo.txt + +# copy from garage to your filesystem +aws s3 cp s3/my_files/cpuinfo.txt /tmp/cpuinfo.txt +``` + +Note that you can use `awscli` for more advanced operations like +creating a bucket, pre-signing a request or managing your website. +[Read the full documentation to know more](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/index.html). + +Some features are however not implemented like ACL or policy. +Check [our s3 compatibility list](@/documentation/reference-manual/s3-compatibility/). ### Other tools for interacting with Garage The following tools can also be used to send and recieve files from/to Garage: -- the [AWS CLI](https://aws.amazon.com/cli/) -- [`rclone`](https://rclone.org/) -- [Cyberduck](https://cyberduck.io/) -- [`s3cmd`](https://s3tools.org/s3cmd) +- [minio-client](@/documentation/connect/cli/#minio-client) +- [s3cmd](@/documentation/connect/cli/#s3cmd) +- [rclone](@/documentation/connect/cli/#rclone) +- [Cyberduck](@/documentation/connect/cli/#cyberduck) +- [WinSCP](@/documentation/connect/cli/#winscp) -Refer to the ["Integrations" section](@/documentation/connect/_index.md) to learn how to -configure application and command line utilities to integrate with Garage. +An exhaustive list is maintained in the ["Integrations" > "Browsing tools" section](@/documentation/connect/_index.md).