This getting started guide will walk you through the basic necessary configuration of the plugin and show you how to set up your first Ansible project in IntelliJ.

• Install plugin and accept license
• Settings for recognizing Ansible files
• Settings for using Ansible collections
• Settings for global navigation and ‘New files’ dialog

A general overview of the IntelliJ platform can be found in the Help of IntelliJ.

First you need to install the OrchidE plugin and accept the license terms. (➞ Prerequisites)

The plugin OrchidE can be installed like any other IntelliJ plugin via the IntelliJ Marketplace:

1. In IntelliJ, open the Settings and go to Plugins.
2. Verify that the YAML plugin (from JetBrains) is installed and enabled.
3. Search for OrchidE and install it. After that you will need to restart the IDE.
   • For Community Editions, you will be prompted to also install the JetBrains Marketplace plugin. This plugin is required for all paid plugins of the JetBrains Marketplace.
4. During the restart, you can start a 30 day trial period or provide a JetBrains user id that has a valid subscription for OrchidE.
5. After restarting, open the Settings again and go to the Languages & Frameworks ➞ OrchidE ➞ OrchidE License section. Accept the license conditions at the end of the license text.
6. Confirm the setting with Apply and continue with the other settings.

OrchidE has several semantic parsers for Ansible playbook, role and variable files. OrchidE does a mapping of the parsers based on the file paths.

Check if the default patterns for mapping fits for your Ansible file structure.

In particular, if you place Ansible playbooks in the root folder of the IntelliJ project, you will need to adapt the patterns. Usually, you only need to customize the playbook patterns.

File paths (simplified) for Ansible file detection:

Ansible variables:

*/group_vars/*
*/host_vars/*
*/roles*/*/vars/*
*/roles*/*/defaults/*
*/playbooks/*/defaults/*
*/playbook/*/defaults/*
*/playbook/*/vars/*
*/playbooks/*/vars/*

Ansible Roles:

*/roles*/*/vars/*
*/roles*/*/defaults/*
*/roles*/*/tasks/*
*/roles*/*/handlers/*
*/roles*/*/meta/*

Ansible Playbooks:

*/ansible/*
*/playbook/*
*/playbooks/*

Configuration dialog:

Make adjustments as follows:

1. In IntelliJ, open the Settings and go to the section Languages & Frameworks ➞ OrchidE ➞ File Type Pattern
2. Add new patterns or modify existing patterns.
   • If your playbooks are in the IntelliJ root folder, change the playbook patterns by removing the playbook/ansible pathname.
   • If you use Ansible task files that you import into playbooks (without roles), create a new pattern of ‘AnsibleType’ RoleTask that matches the file paths of your tasks.

Tip: Always verify if OrchidE recognizes your files correctly using the file icons (after complete configuration, restart of IDE necessary):
playbook file
tasks file
variables file

OrchidE comes with a small set of Ansible Galaxy Collections in the base installation to provide code assistant features. To get the full scope of modules of an Ansible release for syntax highlighting, code completion, navigation, quick documentation and various inspections, an extended package with Ansible Collections and Meta-Data has to be installed.

An up-to-date collection of the most relevant Ansible Galaxy Collections can be installed directly from the IDE, packages for specific Ansible versions need to be installed be installed manually.

Installation of the package with current Ansible Collections.

1. In IntelliJ, open the Settings and go to the section Languages & Frameworks ➞ OrchidE ➞ Extension
2. Configure an empty directory for the location.
3. Check if new updates are available with the link ‘Check for updates’.
4. Start the update with ‘Update definition file’.
5. Apply the settings with the Apply button.
6. Go to the section Languages & Frameworks ➞ OrchidE ➞ Collections.
7. Deselect all collections you do not need.
   

Optional - code completion settings

.

Set your preferred variant for Ansible module names (select Collection ➞ options panel) to be displayed during code completion:

• always “full qualified collection name”
• always only the module name
• always both variants
• based on the listed collections in the meta file (for listed collections the FQCN variant is not displayed)

Apply the setting and close the Settings dialog with the Ok button.

To perform global IDE actions, OrchidE needs the paths to the root folder for playbooks, roles and inventories. With this you can e.g. create a new playbook at any location with the action “New Ansible File” to create a new role with the task’s main file.

Open an existing project with Ansible files or create a new project.

New projects:

1. Create folders for your playbooks, roles and inventories respectively

    <project>
    |-- inventory
    |-- playbooks
    |-- roles
   

   Instead of playbooks you can also take the root folder of the project. But in this case there must be a matching pattern to recognize playbooks.

Configure the Ansible root folders:

1. Open the Project Structure dialog
2. Change to the Facets section
3. Add the OrchidE Ansible facet to one module.
4. Add your root folders to the inventories, playbook and roles sections respectively. Be sure to confirm your selection with Enter.
5. Apply the changes and close the dialog with the Ok button

Exit the IDE and restart before editing your first Ansible files.

1. Open your project
2. Select your IntelliJ module in the project tab (project tree) and create a new Ansible file (context menu: New Ansible File). (You can set the file extension to use under Settings Editor OrchidE einstellen.)
3. Create a playbook
4. Write your first playbook with OrchidE and get to know more features
   • Code Completion of Ansible keywords and tasks
   • Navigation to Ansible files
   • SearchEverywhere of roles, playbooks and inventory variables
   • Navigation to referenced roles, declared variables and file includes.