Creating a new project

The first thing you'll need to do is to create a new rails application using the connector template:

The framework work with either ruby-2.3.x or jruby-9.1.10.0. It is always cleaner to use a new gemset (rvm use jruby-9.1.10.0@connector-test --create). You'll may want to create a .ruby-version file in your project folder so that it takes this gemset by default.

For example:

# With JRuby
rvm use jruby-9.1.10.0@connector-test --create

# With MRI
rvm use ruby-2.4@connector-test --create

# Install rails
gem install rails -v '4.2.10'

Then create your connector project:

rails new <project_name> -m https://raw.githubusercontent.com/Maestrano/maestrano-connector-rails/master/template/maestrano_connector_template.rb

This will generate a new pre-populated project with a custom Gemfile, some controllers and views, a bunch of models for your to complete as well as some example files.

Having troubles with the template? See the details of what it does so that you can understand what's wrong and fix it easily:

Template troubleshooting

Here's what the template do, step by step:

Creates a new rails project
- if an error is encountered while installing the rails gem try running rvm get stable
- if a Redis::CannotConnectError is encountered while generating the project refer to this Gist (MAC/Homebrew users)
Removes the default gemfile and replaces it with a custom one
Removes the default gitignore and replaces it with a custom one
Runs bundle install
Removes useless folders and files (/app/mailers, /test, application.html, application.css, routes.rb)
Copies some files (spec_helper, factories, routes.rb)
Copies and setup some configuration files (Procfile, environments, database, secrets, sidekiq, settings)
Runs bundle exec rails g config:install
Runs bundle exec rails g connector:install (the framework generator, populates a lot of files. Be aware that the generator is not idem potent, so you will have duplicated lines in some files if you run it twice (application_controller for instance))
Runs bundle exec figaro install
Runs bundle exec rake railties:install:migrations
Runs bundle exec rake db:migrate
Creates a new git repo and does an initial commit

If the bundle install fail for whatever reason, some subsequent may fail as well. Have a look at the command output to find out what went wrong and redo the steps that failed.

Configuring the integration with Maestrano

The configuration of your application is driven by the Maestrano Developer Platform, you first need to register and create your application: https://dev-platform.maestrano.com After registering your application, create a new Environment, this will generate a set of API keys to be used to automatically configure your application.

You will then specify your application API keys in the file config/application.yml

# These keys are used to encrypt OAuth tokens (or API Keys) and should be set to 256-bit Keys
encryption_key1: 'E5CD3EDD6E577441CAB9142A1C36A'
encryption_key2: '9B1EF27DF57296E8E1A9143EEB783'

SIDEKIQ_USERNAME: admin
SIDEKIQ_PASSWORD: password

REDIS_URL: redis://localhost:6379/0/connector-test

MNO_DEVPL_HOST: https://developer.maestrano.com
MNO_DEVPL_API_PATH: /api/config/v1/marketplaces
MNO_DEVPL_ENV_NAME: connector-test
MNO_DEVPL_ENV_KEY: [API KEY FROM DEVELOPER PLATFORM]
MNO_DEVPL_ENV_SECRET:[API SECRET FROM DEVELOPER PLATFORM]

Health Check

The endpoints perform health check for connector you just created.

/health_check

/health_check/full

/health_check/full performs complete health check (cache, smtp, database, ...). See health_check and the initalizer for the default configuration. There are also additional health_checks that this URL performs , It checks connectivity to Connec! and Dev Platform.

You can override it by creating an initalizer in the connector, eg:

# my-mnoe-app/config/initializers/health_check.rb
HealthCheck.setup do |config|
  # You can customize which checks happen on a standard health check
  config.standard_checks = %w(cache site)

  # You can set what tests are run with the 'full' or 'all' parameter
  config.full_checks = %w(cache site custom database migrations)
end

You can also add custom checks, Refer to health_check Gem.

Local development

To test against a local development environment, create an Environment named Local in the Developer Platform and use your local application URL as the Application Host: http://localhost:3001

Live testing

To deploy on a public environment. we advise you to deploy the application on Heroku, or on Nex! and register a new Environment using its public endpoint.
To create the application on Nex!, you can refer to these articles:

The application will then be accessible in the MarketPlace from the sandbox environment, which you can access through the Developer Platform.

Browser not supported