How to install a Redmine plugin (Bitnami, Docker)

January 23, 2017 · updated November 4, 2026

To install a Redmine plugin, put it in plugins/<plugin_id>, run bundle install and the plugin migrations, then restart Redmine. Example with View Customize, run in the Redmine directory (the one with config/database.yml):

cd /path/to/redmine
git clone https://github.com/onozaty/redmine-view-customize.git plugins/view_customize
bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production

Then restart Redmine: touch tmp/restart.txt under Passenger, sudo /opt/bitnami/ctlscript.sh restart on a Bitnami server, docker compose restart redmine in Docker. Otherwise, restart the app server, such as Puma. The plugin shows up in Administration → Plugins.

Tested on Redmine 7.0.3, 6.1.6 and 5.1.12 (official image) and Bitnami's 6.0.6 image.

What each step does

  • The folder in plugins/ is named after the plugin ID, not the repository. The README usually gives the right clone command.
  • bundle install installs the plugin's gems. Skip it, and Redmine won't start: Could not find gem 'write_xlsx' in locally installed gems.
  • redmine:plugins:migrate creates the plugin's tables. Back up the database first. Skip it, and pages return error 500: relation "view_customizes" does not exist.
  • The restart loads the plugin: Redmine reads plugins only at startup.

To check from the shell:

bundle exec bin/about

The plugin is listed under Redmine plugins:.

The folder name must match the plugin ID

The ID is in init.rb: Redmine::Plugin.register :view_customize. A plain git clone of that repository creates redmine-view-customize, and a GitHub ZIP unpacks to redmine_drawio-master. Redmine won't start with such a folder:

Redmine::PluginNotFound: Plugin not found. The directory for plugin view_customize should be /usr/src/redmine/plugins/view_customize.

Rename the folder and repeat the steps.

Uninstall a Redmine plugin

cd /path/to/redmine
bundle exec rake redmine:plugins:migrate NAME=view_customize VERSION=0 RAILS_ENV=production
rm -rf plugins/view_customize

Then restart. VERSION=0 rolls back the plugin's migrations and drops its tables with the data, so back up first. Keep the order: without the folder, the task stops with Plugin view_customize was not found, and the tables stay.

Install a plugin on Bitnami Redmine

Bitnami VMs and cloud images keep Redmine in /opt/bitnami/redmine. Bitnami's guide has the same steps:

cd /opt/bitnami/redmine/plugins
git clone https://github.com/onozaty/redmine-view-customize.git view_customize
cd ..
bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production
sudo /opt/bitnami/ctlscript.sh restart

On an old stack with Redmine 3.x, like mine in 2017, Redmine sits in /opt/bitnami/apps/redmine/htdocs. Run the same commands there and restart Apache: sudo /opt/bitnami/ctlscript.sh restart apache. My installer kept ctlscript.sh in /opt/redmine-3.3.2-2.

To see Administration → Plugins, sign in as user, Bitnami's admin login (lost the password?).

Bitnami runs Bundler in deployment mode, so a plugin that adds gems fails with the lockfile can't be updated because frozen mode is set. Unfreeze it and run bundle install again:

bundle config set --local frozen false
bundle install

If a gem fails to build with make failedNo such file or directory - make or extconf.rb failed, install a compiler and the zlib headers, then repeat bundle install:

sudo apt-get install build-essential zlib1g-dev

The guide's --no-deployment is deprecated in Bundler 2.6: the frozen error stays, and the vendor/bundle path disappears from .bundle/config. After that, deployment false reinstalls every gem; frozen false still works.

Bitnami Docker image

Plugins live on the volume in /bitnami/redmine/plugins, and the container migrates them at every start. Gems don't persist: after I recreated the container, it exited at "Executing database migrations" with the frozen lockfile error (visible with BITNAMI_DEBUG=true). The image has no compiler either.

Bitnami is winding down

Free Bitnami images, AWS ones included, no longer get updates. What happened and how to move off Bitnami: Bitnami Redmine install in 2026. For a new server, and for plugins with gems, use the official redmine image.

Install a plugin in Docker

At every start, the official image installs missing gems (bundle check || bundle install) and, if REDMINE_PLUGINS_MIGRATE is set, runs plugin migrations. In compose.yaml:

services:
  redmine:
    build: .
    environment:
      # plus your REDMINE_DB_* settings
      SECRET_KEY_BASE: "a-long-random-string"
      REDMINE_PLUGINS_MIGRATE: "1"
    volumes:
      - ./plugins:/usr/src/redmine/plugins

The stock image has no compiler. If a plugin's gems need one, the container stops with an error like make failedNo such file or directory - make or extconf.rb failed. Hence the Dockerfile next to compose.yaml:

FROM redmine:7.0
RUN apt-get update \
 && apt-get install -y --no-install-recommends build-essential \
 && rm -rf /var/lib/apt/lists/*

git clone https://github.com/onozaty/redmine-view-customize.git plugins/view_customize
# first run; later: docker compose restart redmine
docker compose up -d --build
docker compose exec redmine bundle exec bin/about

Run the last command once docker compose logs redmine shows Listening on. The plugin is listed under Redmine plugins:.

Uninstall:

docker compose exec redmine bundle exec rake redmine:plugins:migrate NAME=view_customize VERSION=0
rm -rf plugins/view_customize
docker compose restart redmine

Set SECRET_KEY_BASE, not REDMINE_SECRET_KEY_BASE: the entrypoint passes the latter only to the server, and docker compose exec fails with Missing `secret_key_base` . Recreating the container reinstalls plugin gems, so that start needs internet.

Redmine 6 and 7 compatibility

Supported: 7.0 (Rails 8.1), 6.1 (Rails 7.2, bug and security fixes), 6.0 (Rails 7.2, security fixes only). 5.x is no longer supported. Plugins break on major upgrades: 6.0 brought Rails 7.2, Propshaft assets and SVG icons; 7.0 brought Rails 8.1 and removed the old icon-* CSS classes.

requires_redmine in init.rb is only a minimum. redmine_banner, archived since 2020, declares 4.0 or later, and on 7.0.3 Redmine doesn't start: LoadError: cannot load such file -- banners/application_hooks. One broken plugin takes Redmine down; remove its folder and restart. A plugin that needs a newer Redmine says so: additionals plugin requires Redmine 7.0 or higher but current is 6.1.6.stable.

Check the last commit and the README requirements. The plugin directory filters by version, as marked by authors: 149 of 1,370 plugins claim 7.0.

Useful Redmine plugins for 6.1 and 7.0

All installed, migrated and loaded on 6.1.6 and 7.0.3 (Additionals on 7.0.3 only). Folder names are in brackets.

  • View Customize 3.6.0 (view_customize): your JavaScript, CSS or HTML on chosen pages.
  • Additionals 4.6.0 (additionals): dashboards, wiki macros, issue rules. Branch stable; for 6.1, tag 4.5.0. No SQLite.
  • Issue Templates 1.2.3 (redmine_issue_templates): issue templates per project.
  • Drawio 1.5.6 (redmine_drawio): draw.io diagrams in wiki and issues.
  • Wiki Extensions 1.3.0 (redmine_wiki_extensions): wiki macros, comments, tags.
  • XLSX format issue exporter 0.3.0 (redmine_xlsx_format_issue_exporter): issue lists to Excel. Needs the compiler in Docker.
  • Redmine OAuth 4.2.3 (redmine_oauth): sign-in with Google, GitHub, GitLab, Azure AD, Okta, Keycloak or OpenID Connect. On 6.1, needs the compiler in Docker.
  • Redmine Dashboard (redmine_dashboard): task and planning boards. Clone main: release 2.16.0 predates Redmine 7.
I do product consulting, build MVPs and teach people to build products themselves. Work with me →
Related posts: