From cfa69177f8cb32124bf8311aa9807c7a798a0e8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20G=C3=BCnther?= Date: Tue, 16 Feb 2016 17:19:43 +0100 Subject: [PATCH] Allow custom gems to be installed through a separate source In a packaged installation, installing custom plugins is unfeasible by default to them breaking on each upgrade of the package (since the Gemfile(.lock) is being overridden. This commit allows users to specify a separated Gemfile, that will be checked by the package installer. --- Gemfile | 6 +- .../packager/installation-guide.md | 66 +++++++++++++++---- lib/tasks/packager.rake | 6 +- 3 files changed, 60 insertions(+), 18 deletions(-) diff --git a/Gemfile b/Gemfile index 0de7f48ba4..03c5e5ae7e 100644 --- a/Gemfile +++ b/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 diff --git a/doc/operation_guides/packager/installation-guide.md b/doc/operation_guides/packager/installation-guide.md index 74517489f1..722015aa56 100644 --- a/doc/operation_guides/packager/installation-guide.md +++ b/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. \ No newline at end of file diff --git a/lib/tasks/packager.rake b/lib/tasks/packager.rake index 5d4518bb3b..8034a01168 100644 --- a/lib/tasks/packager.rake +++ b/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