Installing a plugin in Redmine 7 running on Docker on macOS relies on mounting a local directory for plugins and making sure database migrations run.
Follow this step-by-step guide to install your plugin:
- Step 1: Locate or Create Your Plugins Directory
- Step 2: Download and Extract the Plugin
- Step 3: Restart and Migrate
- Step 4: Verify in Redmine
- Troubleshooting
Step 1: Locate or Create Your Plugins Directory
If you used a docker-compose.yml file to spin up your Redmine instance, you should already have a local volume mapped to /usr/src/redmine/plugins inside the container.
For example, your docker-compose.yml should look similar to this:
services:
redmine:
image: redmine:7
ports:
- "8080:3000"
volumes:
- ./plugins:/usr/src/redmine/plugins # <--- This maps your local plugins folder
- ./files:/usr/src/redmine/files
environment:
- REDMINE_PLUGINS_MIGRATE=1 # <--- Automates database migrations on startup
Note: If you don't have ./plugins mapped on your host machine, create a folder named plugins in your project's local docker directory on your Mac.
Step 2: Download and Extract the Plugin
1. Download your plugin package (usually a .zip or .tar.gz file).
2. Extract the archive on your Mac.
3. Move the unzipped plugin folder into your local ./plugins directory.
Make sure the directory structure looks correct. For example, if your plugin is called redmine_checklists (Checklists plugin can be downloaded here), the path on your Mac should be: ./plugins/redmine_checklists/ (containing init.rb directly inside it).
Step 3: Restart and Migrate
The official Redmine Docker image has a built-in environment variable (REDMINE_PLUGINS_MIGRATE=1) that automatically executes database migrations for any new plugins whenever the container starts.
1. Open your terminal on macOS, navigate to your Docker Compose directory, and restart the container:
docker compose down docker compose up -d
Note: (If you are using an older Docker setup, use docker-compose down and docker-compose up -d).
2. Alternative (Manual Migration): If you prefer not to use the environment variable and your plugin requires a database migration, you can run it manually via the terminal:
docker exec -it <your_redmine_container_name> bundle exec rake redmine:plugins:migrate RAILS_ENV=production
Step 4: Verify in Redmine
1. Open your browser and go to your Redmine instance (e.g., http://localhost:8080).
2. Log in with an Administrator account.
3. Go to Administration > Plugins.
4. Your newly installed plugin should appear in the list. If it provides project-level features, go to an individual project's Settings > Modules to check and enable it.
Troubleshooting
Troubleshooting Tip (Gem Dependencies): If the plugin requires extra Ruby gems (check the plugin's README), the standard official Redmine container might throw an error. If that happens, you will need to create a custom Dockerfile that installs those gems or builds upon redmine:7 with bundle install executed during the build process.