Getting Started & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• lib/manageiq/environment.rb
• lib/generators/manageiq/plugin/templates/README.md
• lib/generators/manageiq/plugin/plugin_generator.rb
• lib/vmdb/plugins.rb

ManageIQ is an open-source Management Platform designed to provide insight, control, and automation across hybrid IT environments, including containers, virtual machines, networks, and storage. The setup process involves initializing the development environment, configuring necessary dependencies such as Bundler and PostgreSQL, and preparing the database schema and initial data.

Sources: README.md:27-39, lib/manageiq/environment.rb:14-29

Environment Initialization

The core environment setup is managed through the ManageIQ::Environment module, which automates the transition from a fresh clone to a running application. This module handles configuration file templating, dependency resolution, and database preparation.

Core Setup Workflow

The manageiq_plugin_update method serves as the primary entry point for environment preparation. It executes a sequence of tasks to ensure the appliance or development workstation matches the required state.

The workflow ensures that essential keys and configuration samples are copied to their active locations before attempting to boot the Rails environment.
Sources: lib/manageiq/environment.rb:14-53

Configuration Files

The system requires specific configuration files to be present in the config/ directory. If these do not exist, the setup utility copies them from provided templates.

Destination Path	Source Template	Purpose
certs/v2_key	certs/v2_key.dev	Encryption key for sensitive data
config/cable.yml	config/cable.yml.sample	ActionCable configuration
config/database.yml	config/database.pg.yml	PostgreSQL connection settings

Sources: lib/manageiq/environment.rb:31-48

Dependency Management

ManageIQ relies on Bundler for managing Ruby gem dependencies. The setup process includes specific logic to handle Bundler versions and local configuration.

• Version Enforcement: The system identifies the required Bundler version from the Gemfile and installs it if the current system version is incompatible.
• Rugged Configuration: Bundler is configured locally to build the rugged gem with SSH support using bundle config set --local build.rugged --with-ssh.
• Gemfile Lock Management: In Continuous Integration (CI) environments, the system can automatically switch to a specific Gemfile.lock.release for non-master branches to ensure consistency.

Sources: lib/manageiq/environment.rb:69-99, lib/manageiq/environment.rb:143-152

Plugin Development Setup

ManageIQ architecture is highly modular, relying on plugins for many features. Setting up a plugin for development requires linking it to a core ManageIQ repository.

Quick Local Setup

For local plugin development, the bin/setup script within a plugin directory performs the following:

1. Clones the core ManageIQ repository into the spec/manageiq directory.
2. Sets up necessary configuration files.
3. Updates the core code via bin/update.

Sources: lib/generators/manageiq/plugin/templates/README.md:14-16

Plugin Generation

New plugins are created using the ManageIQ::PluginGenerator. This generator initializes a Git repository and creates a standard file structure, including gemspecs, RuboCop configurations, and CI workflows.

The generator also modifies the core ManageIQ Gemfile to include the new plugin under the appropriate group, allowing the core engine to discover the plugin's components.
Sources: lib/generators/manageiq/plugin/plugin_generator.rb:23-86

Plugin Initialization and Registration

Once a plugin is added to the environment, it must be initialized. The Vmdb::Plugins class handles the discovery and registration of these components.

• Discovery: The system identifies plugins by selecting Rails::Engine subclasses that implement vmdb_plugin?.
• Component Registration: Initialization involves loading inflections, initializing specific loggers, and registering models for Single Table Inheritance (STI) recognition.
• Content Types: Plugins can provide various types of content, such as Ansible roles, Automate domains, and Dashboard widgets.

Sources: lib/vmdb/plugins.rb:19-21, lib/vmdb/plugins.rb:41-45, lib/vmdb/plugins.rb:108-112

Summary of Setup Tasks

The following table summarizes the primary Rake tasks executed during the setup process to prepare the environment for operation.

Task	Module Method	Description
db:create	create_database	Initializes the PostgreSQL database defined in database.yml.
db:migrate	migrate_database	Runs all pending database migrations.
db:seed	seed_database	Populates the database with initial required data.
test:vmdb:setup	setup_test_environment	Prepares the test database and environment.
evm:automate:reset	reset_automate_domain	Resets the Automate domains to their default state.
update:ui	update_ui	Updates and compiles UI assets.

Sources: lib/manageiq/environment.rb:101-141

The successful completion of these steps prepares a ManageIQ instance for discovery and control of hybrid IT environments, enabling the platform's core automation and integration capabilities.

Sources: README.md:27-39