blue-horizon

web-based user interface to terraforming the public cloud

Requirements

Requirements are based on supported versions from SUSE Linux Enterprise Server 15 SP1.

ruby 2.5.5
rails 5.1.7
puma 3.11.0
sqlite3
terraform 0.13.4
any dependencies of your terraform scripts (e.g. kubectl, helm, etc.)

Contributing

The Ruby project uses rvm to manage a virtual environment for development.

Clone this project
RVM will prompt you to install the required ruby version, if necessary, when entering the project directory.
Install dependencies
```
gem install bundler
bundle
```
If you have trouble with nokogiri, make sure you have development versions of libxml2 & libxslt installed. Install also sqlite-devel. On (open)SUSE:
```
sudo zypper in libxml2-devel libxslt-devel sqlite3-devel
```
If you need to use a path other than ./vendor/ for customization, create a dotenv file (e.g. .env.development) that defines:
- The path to the customization JSON:
```
BLUE_HORIZON_CUSTOMIZER = "./vendor/customization.yml"
```
- The path where terraform sources will be imported from:
```
TERRAFORM_SOURCES_PATH = "./vendor/sources"
```
Place original terraform scripts in /vendor/sources (or your custom TERRAFORM_SOURCES_PATH)

💡 Need a simple script for development? Try this gist.
Initialize a development database
```
rails db:setup
```
Start a development server on http://localhost:3000
```
rails server -b localhost -p 3000
```

Before submitting a change, please be sure it passes all existing tests and conforms with our coding style:

rspec
rubocop

Please be sure to include a screenshot with any view or style changes.

Customization

blue-horizon is pointless, without a set of terraform scripts to work from, and those scripts represent a "target application", which blue-horizon can adapt to support. The vendor path is used by default to host content about the target application.

Terraform sources

⚠ In order for terraform sources to work within blue-horizon, all customization must happen through terraform variables. Source files must not require editing.

.tf, .tmpl, .sh, .yaml/.yml, and .json files can be placed in vendor/sources, and loaded via rails db:setup.

NOTE: The content of those files will be stored in the database, and may be edited by the application user. When terraform runs, it will run on exported content from the database, so it may not be identical to what was initially provided in vendor/sources.

Variables must be defined in terraform JSON format, and named variable*.tf.json. Here some additional tips to customize your variables options:

Variables will be required unless the description includes the word "optional".
Variables with "password" word in the description will be configured as password inputs hiding the content. This keyword value can be changed in the en.yml configuration file changing password_key entry.
Variables with options=[option1,option2] content in the description will create a multi option input. Options are comma-separated, but may include any other punctuation, or spaces. The keyword value can be changed in the en.yml configuration file changing options_key entry.
Variables with [group:some_group_name] will be grouped together (but still listed as ordered in the variables file). The group name will be pulled form I18N configuration, or otherwise titleized. (e.g. `[group:important_things] will render as 'Important Things')
Variable descriptions may include a comment that is not displayed. Any content contained in an HTML comment block  will not be included in the UI, but will be parsed for other customization flags.
Variable descriptions will be rendered as inline markdown in the UI.

Special variables

The following variables will not be displayed on the variable entry form, but will be populated via other application interfaces:

instance_type: the virtual machine type to be used when starting cloud instances; this will be populated from the Size Cluster page.
instance_count: the number of virtual machines to be deployed; this will be populate from the Size Cluster page.
region: the cloud provider's region where services will be established. If blue-horizon is run in a cloud environment; the location will be autodetected via Instance Meta Data Services (IMDS).
⚠ End users should be notified that the application needs to run in the same region where it will be deployed.

To use a different path, set the environment variable TERRAFORM_SOURCES_PATH before seeding the database.

String customization/localization

.yml and .rb files can be placed in vendor/locales, and will be loaded automatically.

See the Rails Internationalization Guide for advice on formatting.

See config/locales/custom-en.yml for a sample/template with keys defined.

To use a different path, set the environment variable BLUE_HORIZON_LOCALIZERS with the directory where custom internationalization files are stored.

Application customization

vendor/customization.json defines configuration keys that can be modified to alter the behavior of the application.

See config/initializers/customization.rb for an explanation of the available keys and options.

To use a different path, set the environment variable BLUE_HORIZON_CUSTOMIZER with the full path of the customization JSON file to load.

Packaging

blue-horizon includes supporting tools and documents to build on an open build service (OBS) instance, such as https://build.opensuse.org

New dependencies

When updating dependencies, add a categorized entry with a comment, in Gemfile.development. If the dependency is required in production, add the gemfile entry only, alphabetically, in Gemfile.production.
Run rails gems:rpmspec:requires and update the specfile (packaging/blue-horizon.spec) with the new dependency set.

Releases

bumpversion is used to tag releases.

bumpversion [major|minor|patch]

Generating a tarball

In order to produce a production-ready tarball, assets need to be precompiled, then the tarball built:

RAILS_ENV=production rails assets:clobber assets:precompile obs:tar

Copy the specfile and move the tarball to an OBS project dir

cp packaging/* path/of/your/project/

diegoakechi/blue-horizon