intellij

This cookbook allows installing and configuring the IntelliJ IDEA IDE. It can
install/update the IntelliJ package, configure "workspace" (the configuration from the idea.config.path directory),
install plugins from the Plugins Repository and configure projects (artifacts, run configurations, SDKs, modules etc.).

The main purpose of this cookbook is to be used as an automatic environment configuration for developers.

Every project has its own configuration which should be added to IDE in order to make it work.
Configuring the IntelliJ IDEA can take some time (there are a lot of places which you can adjust to your needs!)
and - what is worse - can be forgotten, which leads to having a hard time when there is a need to create a new environment
(for example, a new person comes to the project).

Storing your project's configuration inside Chef scripts is good not only because it can configure
the whole IJ configuration for you - it can also be used as documentation for any new person.

NOTICE: This cookbook is NOT idempotent!

One of the Chef's ideology is to create idempotent cookbooks
that will always configure the environment the same way. This is NOT the case for this cookbook.

IntelliJ is a great tool with many configurations and developers are usually customizing their environments. It means that
Chef should not update all of the configuration, which would lead to losing any changes made by the developer, but instead,
it should only make sure that the base configuration stays the same. This way you can always repair your environment by
running the cookbook again - it will only restore the exact configuration written in the recipe and leave personal changes.

Platforms

The cookbook supports Windows and most of the Linux platforms.

Usage

The main way of using the cookbook is to use its LWRP resources.

Recipes

Default.rb

The [default recipe](recipes/default.rb) will only install the IntelliJ IDEA without configuring anything.
It uses the following attributes:

Resources

The main functionality of the cookbook lies within its resources. You can use them by defining dependency for
the cookbook inside the metadata.rb file:

depends 'intellij'

List of currently supported resources:
1. intellij - managing the IntelliJ installation
1. intellij_workspace - managing the IntelliJ global configuration
1. intellij_plugin - managing plugins
1. intellij_sdk - managing installed SDKs
1. intellij_project - managing the IntelliJ's project
1. intellij_module - managing modules inside the IntelliJ's project
1. intellij_run_configuration - managing the IntelliJ's run configurations used in the project
1. intellij_artifact - managing artifacts for IntelliJ's project
1. intellij_changelist - managing change lists inside the IntelliJ's project
1. intellij_docker_integration - managing the Docker configuration inside the IntelliJ workspace
1. intellij_application_server - managing the Java EE servers installed in the IntelliJ workspace
1. intellij_shortcut - managing the shortcuts for the IntelliJ instance

Default

[Default resource](resources/default.rb) intellij is used to download/update the IntelliJ installation.

Example:

intellij 'Installing the 2018.3.4 IntelliJ from the JetBrains download site' do
  path '/home/myuser/IntelliJ'
  version '2018.3.4'
  user 'myuser'
  group 'mygroup'
  edition :community
  properties(
    'idea.config.path': '/home/myuser/workspace',
    'idea.fatal.error.notification': 'enabled'
  )
  action :update
end

intellij 'This will use source defined as property. Version and edition are useful.' do
  path '/home/myuser/IntelliJ'
  version '2018.3.4'
  source 'https://download.jetbrains.com/idea/ideaIU-2018.3.4.win.zip'
  checksum 'bff5d4f07762f2582db80240cfe1e6586cf47c304a7a2c50eb672e63be98229a'
  user 'myuser'
  group 'mygroup'
  edition :community
  action :update
end

Workspace

As a "workspace" we understand the main IntelliJ configuration such as plugins, installed SDKs or applications servers.
Unfortunately, the resource can not guess, where the default (global) configuration lies as the user can have multiple
instances of the IntelliJ installed. Because of this, the resource requires to define the path, where the workspace is
(usually in the home dir or defined inside the idea.config.path parameter).

Normally there is only one workspace defined for all IntelliJ projects. This is good when they have a common configuration,
the IntelliJ also does very good work allowing the user to overwrite it on the project level.

Sometimes it is not enough and there is a need to define separated configuration for some projects - especially if you
work in a company with multiple projects which can have conflicts. There is a way to do it - and this cookbook does support it.
Every time you are creating a configuration using the intellij_workspace resource, it creates a idea.properties file
inside the config directory in the workspace. You can use it to create a special shortcut, which will start the IntelliJ
with proper configuration using the intellij_shortcut resource.

[Resource's configuration](resources/workspace.rb):

Example:

intellij_workspace 'Creating the separated Intellij configuration' do
  path '/home/myuser/workspace'
  default_project '/home/myuser/workspace/project'
  intellij_path '/home/myuser/IntelliJ'
  color_scheme :IntelliJ
  code_style 'styles/Default.xml'
  user 'myuser'
  group 'mygroup'
  action :create
end

intellij_workspace 'This will configure the global instance of configuration' do
  path '/home/myuser/.IdeaIC14'
  default_project '/home/myuser/workspace/project'
  intellij_path '/home/myuser/IntelliJ'
  color_scheme :Darcula
  user 'myuser'
  group 'mygroup'
  action :create
end

Plugin

[This resource](resources/plugin.rb) can be used to install the plugin from the Jetbrains plugins repository.
It will use the JetBrains API to find plugins matching the specified name. It also allows downloading the plugin from
the specific update ("version"). If the plugin is downloaded as the .zip file, it will also automatically unzip it in the
proper location, so the user will not have to do it manually.

Example:

intellij_plugin 'Chef integration' do
  workspace '/home/myuser/.IdeaIC14'
  update 57884
  edition :ultimate
  action :install
end

intellij_plugin 'Docker integration' do
  workspace '/home/myuser/.IdeaIC14'
  respository_filename 'Docker'
  edition :community
  action :install
end

intellij_plugin 'Dart' do
  workspace '/home/myuser/.IdeaIC14'
  user 'myuser'
  group 'mygroup'
  source 'https://downloads/Dart.zip'
  action :update
end

SDK

[This resource](resources/sdk.rb) can be used to install the SDK for all projects using the workspace.
Please, note that not all SDK types are available in the community edition of the IntelliJ.

Example:

intellij_sdk 'Ruby 2.6.1' do
  workspace  '/home/myuser/.IdeaIC14'
  path '/home/myuser/Ruby26-x64'
  type :RUBY_SDK
  action :add
end

intellij_sdk 'Java Open JDK 1.8' do
  workspace  '/home/myuser/.IdeaIC14'
  path '/path/to/java'
  type :JavaSDK
  roots_config <<-EOH
    <roots>
       ... more configuration
    </roots>
  EOH
  action :add
end

Project

[This resource](resources/project.rb) will create a new IntelliJ IDEA's project.

Example:

intellij_project '/home/myuser/workspace/project' do
  project_name 'My fantastic project'
  default_sdk_name 'Ruby 2.6.1'
  default_sdk_type :RUBY_SDK
  code_style 'styles/Project.xml'
  action :create
end

Module

[This resource](resources/project.rb) will create a new module to the existing IntelliJ IDEA's project.
Modules are usually root directories of source codes for your applications. The resource assumes that you already have
them on the disk (either downloaded from the repository or simply created before using this cookbook.).

The resource will automatically detect whether the project is a Maven project. If yes, it will add it to the IJ's
Maven configuration.

It also tries to automatically detect which control version system is used (if any). Currently only
Git repositories will be detected - support for CVS and other ones will be added if needed.

Example:

intellij_module '/home/myuser/Maven-module' do
  project_path '/home/myuser/workspace/project'
  type :JAVA_MODULE
  module_name 'sample-maven-module'
  sdk_name 'JDK 10.0'
  sdk_type :JavaSDK
  action :create
end

Run configuration

[This resource](resources/run_configuration.rb) can be used to define Run configurations used within the project.

Run configurations are usually stored within the .idea/workspace.xml file, inside the RunManager component.
There are many plugins which are adding new possible templates for RC, so it is almost impossible to cover
all of the types in this cookbook. Instead of making a resource for every type, you should provide the configuration as XML.
When using the resource, please make sure that the configuration will be taken from the workspace.xml file.

Example:

intellij_run_configuration 'Start simple batch script' do
  project_path '/home/myuser/workspace/project'
  type 'BatchConfigurationType'
  factory 'Batch'
  open_tool_window false
  body <<-EOH
    <option name="INTERPRETER_OPTIONS" value="" />
    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
    <option name="PARENT_ENVS" value="true" />
    <module name="" />
    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/example.bat" />
    <option name="PARAMETERS" value="Hello" />
    <method v="2" />
  EOH
  action :create
end

intellij_run_configuration 'Create Docker run configuration' do
  project_path '/home/myuser/workspace/project'
  type 'docker-deploy'
  factory 'dockerfile'
  attributes(
    'server-name': 'Local Docker'
  )
  selected true
  body <<-EOH
    <deployment type="docker-compose.yml">
      <settings>
        <option name="sourceFilePath" value="docker/docker-compose.yml" />
      </settings>
    </deployment>
    <method v="2"/>
  EOH
  action :create
end

Artifact

[This resource](resources/artifact.rb) can be used to add an IntelliJ's artifact inside the project.
Similar to the Run configuration resource, it uses whole XML fragments to avoid making very complicated logic for all
possible types of artifacts.

Example:

intellij_artifact 'sample-maven-module:jar' do
  project_path 'C:/Test/Workspace/My Project'
  type 'jar'
  root <<-EOH
    <root id="archive" name="sample-maven-module.jar">
      <element id="module-output" name="sample-maven-module" />
    </root>
  EOH
  action :create
end

Changelist

[This resource](resources/changelist.rb) allows configuring the change lists within the IntelliJ.
Change lists are useful because they allow the user to distinguish the changes made in code into the smaller groups.
Another great way to use them is to mark changes as "not pushable" (sometimes project requires to change the files
without committing them - this way you will not push them by mistake).

Please note that if the IntelliJ contains only one change list, it will be automatically set up as the default one,
meaning that any future edits will be saved in it. If you still want to have the Default change list, you have to
set it up using the same resource.

Examples:

intellij_changelist 'This will make sure that the change list will be defined exactly as specified' do
  project_path '/home/user/my/project'
  changelist_name 'My changelist'
  comment 'Testing the change lists mechanism'
  files %w(/home/user/my/project/file1.txt /home/user/my/project/file2.txt)
  action :create
end

intellij_changelist 'This will only update the comment and set up the change list as default' do
  project_path '/home/user/my/project'
  changelist_name 'My changelist'
  comment 'Changed the comment'
  default true
  action :update
end

intellij_changelist 'This will only update the files within the change list exactly as provided' do
  project_path '/home/user/my/project'
  changelist_name 'My changelist'
  files %w(/home/user/my/project/new-file.txt)
  action :update
end

intellij_changelist 'This will update the change list and add files instead of replacing them' do
  project_path '/home/user/my/project'
  changelist_name 'My changelist'
  comment 'Changed the comment again'
  files %w(/home/user/my/project/added-file.txt)
  action :add_files
end

intellij_changelist 'This will update the change list and remove the file from it' do
  project_path '/home/user/my/project'
  changelist_name 'My changelist'
  default false
  files %w(/home/user/my/project/new-file.txt)
  action :delete_files
end

intellij_changelist 'This will completely remove the change list' do
  project_path node['intellij']['tests']['project_path']
  changelist_name 'My changelist'
  action delete
end

Docker integration

[This resource](resources/docker_integration.rb) can be used to configure the integration with Docker within the IntelliJ.
It can automatically install the plugin, configure the Docker connection (remembering about proper settings like sockets
addresses) and add Docker registries.

Please make sure that the Docker integration plugin is
correctly installed in the IntelliJ's workspace.

Examples:

intellij_docker_integration 'Local Docker' do
  workspace_path '/home/myuser/workspace'
  registries(
    'Docker Registry': {
      address: 'registry.hub.docker.com',
      username: 'myuser',
      email: 'my@gmail.com',
    }
  )
  shared_directories(
    '/home/local/path': '/path/inside/docker'
  )
  user 'myuser'
  group 'mygroup'
end

intellij_docker_integration 'Local Docker' do
  workspace_path '/home/myuser/workspace'
  machine_name 'local_machine'
  registries(
    'My private registry': {
      address: 'my.company.registry.address',
      email: 'my@mycompany.com',
    }
  )
  shared_directories(
    '/home/local/path': '/changes/path/in/docker',
    '/home/local/path2': '/path/inside/docker'
  )
  action :merge
end

Application server

[This resource](resources/application_server.rb) can be used to add an instance of a Java EE server to the IntelliJ's workspace.
Please remember, that this functionality works only in the Ultimate version of the IntelliJ.

Examples:

intellij_application_server 'Local Apache Tomcat' do
  type :Tomcat
  path node['intellij']['example']['tomcat_path']
  user user
  group group
  workspace_path 'C:/Tests/Workspace'
  action :create
end

intellij_application_server 'Local WildFly' do
  workspace_path 'C:/Tests/Workspace'
  action :delete
end

Shortcut

[This resource](resources/shortcut.rb) can be used to create the shortcut for the IntelliJ IDEA instance.
It also supports overriding the main configuration by defining the idea_properties property (by changing
the IDEA_PROPERTIES environment variable).

Examples:

intellij_shortcut 'C:/Program Files/JetBrains/IntelliJ'

intellij_shortcut 'This will create the shortcut in the different directory and name, using separated configuration' do
  intellij_path 'C:/Program Files/JetBrains/IntelliJ'
  shortcut_name 'My shortcut'
  idea_properties 'C:/Workspace/config/idea.properties'
  directory 'C:/Shortcuts/'
  action :create
end

intellij_shortcut 'This will create a desktop shortcut using global configuration' do
  intellij_path '/home/user/JetBrains/IntelliJ'
  shortcut_name 'My shortcut'
  action :create
end

More examples

You can find more examples of usage for every resource inside the [recipes](recipes) directory.