feat: S3 GUI client integration instructions (#35)

project-n-oss · May 31, 2023 · c3fc76f · c3fc76f
1 parent 3402935
commit c3fc76f
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 15 deletions.
diff --git a/integrations/cyberduck/README.md b/integrations/cyberduck/README.md
@@ -9,6 +9,7 @@ To get started, you will need to run SideKick on your machine. Head over to the
 Next, extract the binary from the downloaded file:
 
 **macOS**
+
 ```bash
 tar -xvf <artifact>.tar.gz
 ```
@@ -18,8 +19,8 @@ Right-click on the downloaded file in the File Explorer and click "Extract All".
 
 Before running the executable, make sure the following environment variables are set:
 
-* `BOLT_CUSTOM_DOMAIN`: This is the custom domain you chose during setup.
-* `AWS_REGION`: This is the region of your Bolt deployment.
+- `BOLT_CUSTOM_DOMAIN`: This is the custom domain you chose during setup.
+- `AWS_REGION`: This is the region of your Bolt deployment.
 
 **macOS**
 
@@ -29,11 +30,33 @@ export AWS_REGION="your-bolt-region"
 ```
 
 **Windows**
+
 ```bash
 set BOLT_CUSTOM_DOMAIN=your-bolt-domain.com
 set AWS_REGION=your-bolt-region
 ```
 
 ## CyberDuck configuration
 
-Now that you have SideKick running, download the SideKick CyberDuck bookmark file from [here](./sidekick.duck). Drag it onto your CyberDuck window and enter your AWS credentials.
+Now that you have SideKick running, start CyberDuck.
+
+First, you'll need to enable the "S3 (HTTP)" profile.
+
+1. Navigate to Settings
+
+Windows: Click "Edit" and then "Preferences"
+macOS: Click "CyberDuck" in the top left corner and then "Settings"
+
+2. Then navigate to "Profiles" and search for "s3 http"
+
+3. Tick "S3 (HTTP)"
+
+Now download the SideKick CyberDuck bookmark file, drag it onto your CyberDuck Bookmarks view and enter your AWS credentials.
+
+**Available CyberDuck profiles**
+
+- **Single-bucket profile** - [profile](./sidekick-single-bucket.duck)
+
+Configured to access a single crunched bucket via sidekick. Before dragging the bookmark file onto the CyberDuck window, open the file in a text editor and replace `bucket-name` with the name of your bucket.
+
+- **Multi-bucket profile** - configure to access all accessible buckets (crunched and not) - tbd
diff --git a/integrations/cyberduck/sidekick-single-bucket.duck b/integrations/cyberduck/sidekick-single-bucket.duck
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Protocol</key>
+  <string>s3</string>
+  <key>Provider</key>
+  <string>s3-http</string>
+  <key>Scheme</key>
+  <string>http</string>
+  <key>Nickname</key>
+  <string>SideKick - Single Bucket</string>
+  <key>Hostname</key>
+  <string>localhost</string>
+  <key>Port</key>
+  <string>7075</string>
+  <key>Path</key>
+  <string>/bucket-name</string>
+</dict>
+</plist>
diff --git a/integrations/cyberduck/sidekick.duck b/integrations/cyberduck/sidekick.duck
@@ -2,17 +2,19 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-	<key>Protocol</key>
-	<string>s3</string>
-	<key>Provider</key>
-	<string>s3-http</string>
-	<key>Nickname</key>
-	<string>SideKick</string>
-	<key>UUID</key>
-	<string>a4a82250-3ea9-4353-b0e0-525f12e7810e</string>
-	<key>Hostname</key>
-	<string>localhost</string>
-	<key>Port</key>
-	<string>7075</string>
+  <key>Protocol</key>
+  <string>s3</string>
+  <key>Provider</key>
+  <string>s3-http</string>
+  <key>Scheme</key>
+  <string>http</string>
+  <key>Nickname</key>
+  <string>SideKick</string>
+  <key>Hostname</key>
+  <string>localhost</string>
+  <key>Port</key>
+  <string>7075</string>
+  <key>Path</key>
+  <string>/kote-test-data</string>
 </dict>
 </plist>
diff --git a/integrations/s3browser/README.md b/integrations/s3browser/README.md
@@ -0,0 +1,40 @@
+# S3 Browser integration
+
+This guide will walk you through how to seamlessly integrate SideKick with your [S3 Browser](https://s3browser.com/) instance running on your machine.
+
+## SideKick configuration
+
+To get started, you will need to run SideKick on your machine. Head over to the [releases page](https://github.com/project-n-oss/sidekick/releases) and download the package for your OS and architecture.
+
+Next, extract the binary from the downloaded file:
+
+**Windows**
+Right-click on the downloaded file in the File Explorer and click "Extract All".
+
+Before running the executable, make sure the following environment variables are set:
+
+- `BOLT_CUSTOM_DOMAIN`: This is the custom domain you chose during setup.
+- `AWS_REGION`: This is the region of your Bolt deployment.
+
+**Windows**
+
+```bash
+set BOLT_CUSTOM_DOMAIN=your-bolt-domain.com
+set AWS_REGION=your-bolt-region
+```
+
+## S3 Browser configuration
+
+1. Add a new account with "S3 Compatible Storage" type
+2. REST Endpoint: `localhost:7075`
+3. Enter AWS Access Key, AWS Secret Key
+4. Make sure "Use secure transfer" is **not checked**
+5. Click on “Advanced Settings”
+6. Under "Signature Version” select "Signature V4"
+7. Configure all regions where your buckets live like below, save changes and refresh the bucket list.
+
+```
+DefaultRegion=bolt-region
+USE1=us-east-1
+USW1=us-west-1
+```