Alchemy CMS Cloudinary Integration

This skill helps you work with the Alchemy Cloudinary Rails engine, which integrates Cloudinary cloud image hosting with Alchemy CMS. It replaces Alchemy's default Dragonfly storage with Cloudinary's cloud-based image service.

Architecture Understanding

Core Integration Points

**Engine Initialization** (`lib/alchemy_cloudinary/engine.rb`)

**Storage Layer Components**

URL Generation Behavior

The `CloudinaryUrl` class extends `Alchemy::StorageAdapter::Dragonfly::PictureUrl` and:

1. Builds transformation arrays from options (crop, resize)

2. Calculates crop coordinates from `crop_from` and `crop_size`

3. Calls `picture.image_file.remote_url()` with Cloudinary transformation syntax

4. Supports modes: `fill` (crop), `fit` (upsample), `limit` (default)

Testing

Run the full test suite:

```bash

bundle exec rake spec

```

Run specific test file:

```bash

bundle exec rspec spec/models/alchemy/storage_adapter/dragonfly/cloudinary_url_spec.rb

```

Run with reproducible seed:

```bash

bundle exec rspec --seed 12345

```

Development Setup

Install dependencies:

```bash

bundle install

```

Build the gem:

```bash

gem build alchemy_cloudinary.gemspec

```

Install locally:

```bash

gem install alchemy_cloudinary-*.gem

```

Configuration

Set up Cloudinary credentials using one of these methods:

**Environment Variable (Production)**

```bash

export CLOUDINARY_URL=cloudinary://api_key:api_secret@cloud_name

```

**Configuration File** (`config/cloudinary.yml`)

```yaml

production:

cloud_name: your_cloud_name

api_key: your_api_key

api_secret: your_api_secret

```

**Rails Initializer** (`config/initializers/cloudinary.rb`)

```ruby

Cloudinary.config do |config|

config.cloud_name = 'your_cloud_name'

config.api_key = 'your_api_key'

config.api_secret = 'your_api_secret'

end

```

Dependencies

Test Architecture

Tests use minimal loading approach:

Key Files

Common Tasks

When implementing new transformation features:

1. Add transformation logic to `CloudinaryUrl` class

2. Update tests in `spec/models/alchemy/storage_adapter/dragonfly/cloudinary_url_spec.rb`

3. Ensure backward compatibility with Alchemy's `PictureUrl` interface

When debugging storage issues:

1. Check `DragonflyDataStore` for upload/download logic

2. Verify Cloudinary API credentials are configured

3. Review transformation parameters passed to `remote_url()`