Merge pull request #4158 from oliverguenther/feature/custom-plugins

Allow custom gems to be installed through a separate source

Gemfile

@@ -246,8 +246,10 @@ group :docker do
   gem 'newrelic_rpm', require: !!ENV['HEROKU']
 end
 
-# Load Gemfile.local, Gemfile.plugins and plugins' Gemfiles
-Dir.glob File.expand_path('../{Gemfile.local,Gemfile.plugins,lib/plugins/*/Gemfile}', __FILE__) do |file|
+# Load Gemfile.local, Gemfile.plugins, plugins', and custom Gemfiles
+gemfiles = Dir.glob File.expand_path('../{Gemfile.local,Gemfile.plugins,lib/plugins/*/Gemfile}', __FILE__)
+gemfiles << ENV['CUSTOM_PLUGIN_GEMFILE'] unless ENV['CUSTOM_PLUGIN_GEMFILE'].nil?
+gemfiles.each do |file|
   next unless File.readable?(file)
   eval_gemfile(file)
 end

doc/operation_guides/packager/installation-guide.md

@@ -216,20 +216,6 @@ You can list all of the environment variables accessible to the application by r
     RAILS_CACHE_STORE=memcache
     SESSION_STORE=cache_store
 
-## Advanced: manually set configuration options
-
-The installation wizard should take care of setting the most important
-configuration options automatically based on your choices. However you might
-want to tweak an option not supported by the wizard, in which case you can
-directly set it using the `config:set` command of the `openproject` CLI.
-
-For instance if you wanted to change the session store you would do:
-
-    sudo openproject config:set SESSION_STORE=active_record_store
-    sudo service openproject restart
-
-In most cases though, you should always try to `reconfigure` the application first.
-
 # Upgrade to a newer version
 
 Upgrading the OpenProject is as easy as installing a newer OpenProject package
@@ -252,3 +238,55 @@ and running the `openproject configure` command.
     sudo zypper update openproject
     sudo openproject configure
 
+
+# Advanced
+
+## Adding custom plugins to the installation
+
+[A number of plugins](https://www.openproject.org/open-source/openproject-plugins/) exist for use with OpenProject. Most plugins that are maintained by us are shipping with OpenProject, however there are several plugins contributed by the community.
+
+Previously, using them in a packaged installation was not possible without losing your changes on every upgrade. With the following steps, you can now use third party plugins.
+
+**Note**: We cannot guarantee upgrade compatibility for third party plugins nor do we provide support for them. Please carefully check whether the plugins you use are available in newer versions before upgrading your installation.
+
+#### 1. Add a custom Gemfile
+
+If you have a plugin you wish to add to your packaged OpenProject installation, create a separate Gemfile with the Gem dependencies, such as the following:
+
+```
+gem 'openproject-emoji', git: 'https://github.com/tessi/openproject-emoji.git', :branch => 'op-5-stable'
+```
+
+We suggest to store the Gemfile under `/etc/openproject/Gemfile.custom`, but the choice is up to you, just make sure the `openproject` user is able to read it.
+
+#### 2. Propagate the Gemfile to the package
+
+You have to tell your installation to use the custom gemfile via a config setting:
+
+```
+openproject config:set CUSTOM_PLUGIN_GEMFILE=/etc/openproject/Gemfile.custom
+```
+
+#### 3. Re-run the installer
+
+To re-bundle the application including the new plugins, as well as running migrations and precompiling their assets, simply re-run the installer while using the same configuration as before.
+
+```
+openproject configure
+```
+
+Using `configure` will take your previous decisions in the installer and simply re-apply them, which is an idempotent operation. It will detect the Gemfile config option being set and re-bundle the application.
+
+## Manually set configuration options
+
+The installation wizard should take care of setting the most important
+configuration options automatically based on your choices. However you might
+want to tweak an option not supported by the wizard, in which case you can
+directly set it using the `config:set` command of the `openproject` CLI.
+
+For instance if you wanted to change the session store you would do:
+
+    sudo openproject config:set SESSION_STORE=active_record_store
+    sudo service openproject restart
+
+In most cases though, you should always try to `reconfigure` the application first.

lib/tasks/packager.rake

@@ -47,11 +47,13 @@ namespace :packager do
   # avoids to load the environment multiple times
   task postinstall: [:environment, 'setup:scm'] do
 
-    # Precompile assets when requested
+    # We need to precompile assets when either
+    # 1. packager requested it (e.g., due to a server prefix being set)
+    # 2. When a custom Gemfile is added
     if ENV['REBUILD_ASSETS'] == 'true'
       Rake::Task['assets:precompile'].invoke
       FileUtils.chmod_R 'a+r', "#{ENV['APP_HOME']}/public/assets/"
-      shell_setup(['config:set', 'REBUILD_ASSETS="false"'])
+      shell_setup(['config:set', 'REBUILD_ASSETS=""'])
     end
 
     # Persist configuration