Erste Schritte mit OrchidE

Diese Erste Schritte Anleitung führt Sie durch die grundlegend nötige Konfiguration des Plugins und zeigt die Einrichtung Ihres ersten Ansible Projekts in IntelliJ.

Diese Anleitung setzt die OrchidE Version 2022.1.5 oder neuer voraus.

Einen allgemeinen Überblick über die IntelliJ Plattform gibt es in der Hilfe zu IntelliJ.

Plugin installieren und Lizenz akzeptieren

Zuerst müssen Sie das Plugin OrchidE installieren und die Lizenzbedingungen akzeptieren. (➞ Voraussetzungen)

Das Plugin OrchidE lässt sich wie jedes andere IntelliJ Plugin über den IntelliJ Marketplace installieren:

  1. Öffnen Sie in IntelliJ die Settings und gehen Sie zu Plugins.
  2. Verifizieren Sie, daß das Plugin YAML (von JetBrains) installiert und aktiviert ist.
  3. Suchen Sie nach OrchidE und installieren es. Danach ist ein Neustart der IDE nötig.
    • Bei Community Editions werden Sie aufgefordert, auch das JetBrains Marketplace Plugin zu installieren. Dieses Plugin wird für alle Paid-Plugins des Marktplatzes von JetBrains benötigt.
  4. Während des Neustarts können Sie einen 30 Tage Testzeitraum starten oder eine JetBrains Benutzer-Id angeben, die über eine Lizenz verfügt.
  5. Nach dem Neustart öffnen Sie erneut die Settings und gehen zu dem Abschnitt Languages & Frameworks ➞ OrchidE ➞ OrchidE License. Akzeptieren Sie die Lizenzbedingungen am Ende des Lizenztextes.
  6. Bestätigen Sie die Einstellung mit Ok.

Einstellungen für das Erkennen von Ansible Dateien

OrchidE verfügt über verschiedene semantische Parser für Ansible Playbooks, Roles und Variablen-Dateien.

Damit OrchidE Dateien mit dem richtigen Parser lädt müssen die Root-Ordner zu Playbooks, Roles und Inventories konfiguriert werden. Ohne diese Konfiguration werden Ansible Dateien nicht korrekt dargestellt und übliche IDE Features funktionieren nicht.

Öffnen Sie ein bestehendes Projekt mit Ansible Dateien oder erstellen Sie ein neues Projekt.

Für neue Projekte:

  1. Erstellen Sie jeweils Ordner für Ihre Playbooks, Roles und Inventories 
     <project>
 |-- inventory
 |-- playbooks
 |-- roles

    Anstatt playbooks können Sie auch den Root-Ordner des Projekts nehmen.


Konfigurieren Sie die Zuordnung von Ansible Playbooks, Roles und Inventories:

  1. Öffnen Sie die IntelliJ Settings und gehen Sie zu Languages & Frameworks -> OrchidE -> Ansible Folder Mapping.
  2. Selektieren Sie die Checkbox ‘Use Ansible Folder Mapping settings’. (ab Version 2022.1.5 Default, falls keine älteren Einstellungen existieren.)
  3. Fügen Sie die Ordner für Inventories hinzu
  4. Fügen Sie die Ordner für Playbooks hinzu. Nehmen Sie das Projekt Verzeichnis, wenn kein extra Ordner für Playbooks verwendet wird.
  5. Für Tasks (via include_tasks) und Variablen (include_vars, vars_files) innerhalb des Playbook Ordners können Sie weitere Ausnahmen definieren.
  6. Fügen Sie die Ordner für Roles hinzu. Nehmen Sie das Projekt Verzeichnis, wenn das Projekt nur aus einer Rolle besteht und kein extra Ordner für die Rolle verwendet wird.
  7. Für Playbooks (z.B in molecule) und Variablen innerhalb des Roles-Ordners können Sie weitere Ausnahmen definieren.
  8. Fügen Sie Ausnahmen (Global Ignores) für YAML Dateien hinzu, die keine Ansible Dateien sind - z.B Konfigurationsdateien für CI Systeme.
  9. Übernehmen Sie die Änderungen mit dem Apply-Button.

Tip: Verifizieren Sie immer ob OrchidE Ihre Dateien später richtig erkennt (nach vollständiger Konfiguration) anhand der Datei-Symbole:
Playbook Playbook Datei
Tasks Tasks Datei
Variables Variablen Datei

Einstellungen für das Nutzen von Ansible Collections

OrchidE kommt in der Grundinstallation mit einer kleinen Auswahl an Ansible Galaxy Collections um Code Assistant Funktionen bereitzustellen. Um den vollen Umfang an Modulen eines Ansible Releases für Syntax Highlighting, Code Completion, Navigation, Quick Documentation und diversen Inspections zu bekommen, muss ein erweitertes Paket mit Ansible Collections und Meta-Daten installiert werden.

Eine aktuelle Sammlung der relevantesten Ansible Galaxy Collections können Sie direkt aus der IDE installieren, Pakete für bestimmte Ansible Versionen müssen manuell installiert werden.

Installation des Paketes mit aktuellen Ansible Collections

  1. Öffnen Sie in IntelliJ die Settings und gehen Sie zum Abschnitt Languages & Frameworks ➞ OrchidE ➞ Extension
  2. Konfigurieren Sie für den Speicherort ein leeres Verzeichnis
  3. Prüfen Sie ob neue Updates vorhanden sind mit dem Link ‘Check for updates’
  4. Starten Sie das Update mit ‘Update definition file’
  5. Übernehmen Sie die Einstellungen mit dem ‘Apply’-Button
  6. Wechseln Sie zum Abschnitt Languages & Frameworks ➞ OrchidE ➞ Collections
  7. Deselektieren Sie alle Collections die Sie nicht benötigen

Optional - Code Completion Einstellungen

Es wird empfohlen alle Collections die nicht benutzt werden abzuwählen. Das erhöht die Übersichtlichkeit und Performance.

OrchidE code completion settings dialog - collections.

Stellen Sie Ihre bevorzugte Variante für Ansible Modul Namen ein (Collection auswählen ➞ Auswahlbox) die bei der Code Completion angezeigt werden soll:

  • immer “full qualified collection name”
  • immer nur den Modul Namen
  • immer beide Varianten
  • basierend auf den aufgeführten Collections in der Meta Datei (für aufgeführte Collections wird die FQCN Variante nicht angezeigt)

Übernehmen Sie die Einstellungen und schließen den Settings Dialog mit dem ‘Ok’-Button.

Beenden und starten Sie die IDE neu, bevor Sie Ihre erste Ansible Dateien editieren.

Das erste Playbook

  1. Öffnen Sie Ihr Projekt
  2. Selektieren Sie Ihr IntelliJ Module im Projekt Tab (Projekt Baum) und erzeugen ein neues Ansible File (Kontextmenü: New ➞ Ansible File) (Die genutzte Datei-Erweiterung können Sie unter Settings ➞ Editor ➞ OrchidE einstellen.)
  3. Erstellen Sie ein Playbook
  4. Schreiben Sie erstes Playbook mit OrchidE und lernen Sie weitere Features