## Installation

To use Rabata.io with Ruby, you'll need to install the AWS SDK for Ruby.

### Install AWS SDK

```bash
$ gem install aws-sdk-s3
```

For a new project, you might want to use Bundler:

```bash
$ mkdir my-rabata-project
$ cd my-rabata-project
$ bundle init
$ echo 'gem "aws-sdk-s3", "~> 1.114"' >> Gemfile
$ bundle install
```

## Configuration

There are several ways to configure the AWS SDK for Ruby to work with Rabata.io.

### Method 1: Using AWS Credentials File

If you've already configured the AWS CLI as shown in the [AWS CLI Quickstart](/docs/quickstart/aws-cli/), the SDK will automatically use those credentials.

### Method 2: Explicit Configuration in Code

You can explicitly configure the S3 client in your code:

```ruby
require 'aws-sdk-s3'

# Create an S3 client with Rabata.io endpoint
s3_client = Aws::S3::Client.new(
  region: 'us-east-1',
  endpoint: 'https://s3.us-east-1.rabata.io',
  credentials: Aws::Credentials.new(
    'YOUR_ACCESS_KEY',
    'YOUR_SECRET_KEY'
  )
)
```

### Method 3: Using Environment Variables

You can set environment variables to configure the SDK:

```bash
# Set these environment variables before running your Ruby script
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
export AWS_REGION=us-east-1
```

Then in your code:

```ruby
require 'aws-sdk-s3'

# Create an S3 client with Rabata.io endpoint
s3_client = Aws::S3::Client.new(
  endpoint: 'https://s3.us-east-1.rabata.io'
)
```

> **Security Note**: Never hardcode your credentials in your source code, especially if it's stored in a version control system. Use environment variables, AWS credentials file, or a secure secrets management system.

### Note on Older Ruby Libraries

If you're using older versions of the AWS SDK for Ruby (v2 or earlier) or alternative S3 libraries like fog-aws, you may need to explicitly configure signature version 4 in your client configuration. Rabata.io requires signature v4 for authentication. Modern versions of aws-sdk-s3 (v3) automatically use signature v4 for custom S3-compatible endpoints.

## Basic Operations

Here are some common operations you can perform with the AWS SDK for Ruby and Rabata.io.

### Bucket Operations

#### List All Buckets

```ruby
require 'aws-sdk-s3'

s3_client = Aws::S3::Client.new(
  region: 'us-east-1',
  endpoint: 'https://s3.us-east-1.rabata.io',
  credentials: Aws::Credentials.new(
    'YOUR_ACCESS_KEY',
    'YOUR_SECRET_KEY'
  )
)

response = s3_client.list_buckets

puts "Buckets:"
response.buckets.each do |bucket|
  puts "  #{bucket.name}"
end
```

#### Create a Bucket

```ruby
s3_client.create_bucket(bucket: 'my-bucket-name')
```

#### Delete a Bucket

```ruby
s3_client.delete_bucket(bucket: 'my-bucket-name')
```

Note: The bucket must be empty before it can be deleted.

### Object Operations

#### List Objects in a Bucket

```ruby
response = s3_client.list_objects_v2(bucket: 'my-bucket-name')

puts "Objects in bucket my-bucket-name:"
if response.contents
  response.contents.each do |obj|
    puts "  #{obj.key} (#{obj.size} bytes)"
  end
end
```

#### Upload a File

```ruby
File.open('local-file.txt', 'rb') do |file|
  s3_client.put_object(
    bucket: 'my-bucket-name',
    key: 'remote-file.txt',
    body: file
  )
end

puts "File uploaded successfully"
```

#### Download a File

```ruby
response = s3_client.get_object(
  bucket: 'my-bucket-name',
  key: 'remote-file.txt'
)

File.open('local-file.txt', 'wb') do |file|
  file.write(response.body.read)
end

puts "File downloaded successfully"
```

#### Delete a File

```ruby
s3_client.delete_object(
  bucket: 'my-bucket-name',
  key: 'file-to-delete.txt'
)

puts "File deleted successfully"
```

## Advanced Operations

Here are some more advanced operations you can perform with the AWS SDK for Ruby and Rabata.io.

### Working with Object Metadata

```ruby
s3_client.put_object(
  bucket: 'my-bucket-name',
  key: 'file-with-metadata.txt',
  body: 'Hello, World!',
  metadata: {
    'custom-key' => 'custom-value',
    'content-type' => 'text/plain'
  }
)

puts "File uploaded with metadata"
```
<!--
### Setting Object ACLs

```ruby
s3_client.put_object(
  bucket: 'my-bucket-name',
  key: 'public-file.txt',
  body: 'This is a public file',
  acl: 'public-read'
)

puts "Public file uploaded"
``` -->

### Using Presigned URLs

Generate a presigned URL to allow temporary access to an object:

```ruby
signer = Aws::S3::Presigner.new(client: s3_client)

url = signer.presigned_url(
  :get_object,
  bucket: 'my-bucket-name',
  key: 'private-file.txt',
  expires_in: 3600 # URL expires in 1 hour
)

puts "Presigned URL: #{url}"
```

### Using S3 Resource (Higher-level API)

The AWS SDK for Ruby also provides a higher-level resource interface:

```ruby
require 'aws-sdk-s3'

s3_resource = Aws::S3::Resource.new(
  region: 'us-east-1',
  endpoint: 'https://s3.us-east-1.rabata.io',
  credentials: Aws::Credentials.new(
    'YOUR_ACCESS_KEY',
    'YOUR_SECRET_KEY'
  )
)

# List all buckets
s3_resource.buckets.each do |bucket|
  puts bucket.name
end

# Get a bucket
bucket = s3_resource.bucket('my-bucket-name')

# List all objects in a bucket
bucket.objects.each do |obj|
  puts "#{obj.key} (#{obj.size} bytes)"
end

# Upload a file
bucket.object('remote-file.txt').upload_file('local-file.txt')

# Download a file
bucket.object('remote-file.txt').download_file('local-file.txt')
```

## Error Handling

It's important to handle errors properly when working with S3:

```ruby
require 'aws-sdk-s3'

s3_client = Aws::S3::Client.new(
  region: 'us-east-1',
  endpoint: 'https://s3.us-east-1.rabata.io',
  credentials: Aws::Credentials.new(
    'YOUR_ACCESS_KEY',
    'YOUR_SECRET_KEY'
  )
)

begin
  response = s3_client.get_object(
    bucket: 'my-bucket-name',
    key: 'my-object.txt'
  )
  content = response.body.read
  puts content
rescue Aws::S3::Errors::NoSuchKey
  puts "The object does not exist."
rescue Aws::S3::Errors::NoSuchBucket
  puts "The bucket does not exist."
rescue Aws::S3::Errors::ServiceError => e
  puts "An error occurred: #{e.message}"
end
```

<div class="docs-article__actions">
  <a href="/docs/quickstart/rails/" class="btn btn--secondary">Rails Integration</a>
  <a href="/docs/quickstart/aws-cli/" class="btn btn--secondary">AWS CLI Quickstart</a>
</div>