Going further: Docker options, debugging and customizing Redmine

  1. “image” vs “build” tags

 

Using the "image" tag you will be using pre-existing images from official repositories such as DockerHub or your own repository as the images are.

 

The "build" tag allows you to take the same images but adapt them to your needs for that particular project.

This is useful when:

  • adapting official images that are almost prefect for your use but not quite
  • using the same image in different environments without having to store multiple versions of the same image in your repository. The built image will be stored on the host running the image.

 

It will re-run the docker-compose process and execute any changes detected in the docker-compose.yml file.

To build your customized image in this instance:

  1. comment out

image: redmine:5.0.5

  1. uncomment

build: /opt/redminedocker/configs

  1. Update your container by executing command:

sudo docker-compose up -d

 

 

The build process will call the Dockerfile to get the parameters and actions to be run to create your customized image.

 

  1. Understanding the Dockerfile

 

Below will be a few examples of Dockerfile contents from running servers.

Example 1 is the file used with the docker-compose.yml above when using the "build" tag.

Example 1

 

FROM redmine:5.0.5
RUN set -ex; \
apt update;
RUN apt-get install dialog apt-utils -y
RUN apt install cron libreoffice -y
RUN apt-get install -y build-essential
RUN apt install pandoc -y
RUN apt-get clean
RUN apt-get autoclean
RUN apt-get autoremove
RUN cd /usr/src/redmine
RUN gem install json -v '2.6.1'
RUN mkdir root
CMD ["rails", "server", "-b", "0.0.0.0"]

  • FROM is to set the image used as starting point
  • RUN allows commands to be passed. You can either combine commands in a single RUN line using \ or have multiple RUN lines
  • CMD details the arguments for the ENTRYPOINT process.

This file will install a few additional packages (CRON, libreoffice, pandoc...) that are used for some of the plugins I usually install.

It also installs JSON Gem at a specific version also because of a plugin compatibility issue.

Example 2

FROM redmine:5.0.5
MAINTAINER Nicolas
RUN yum -y update && \
yum clean all
COPY ./script.sh /
RUN chmod +x /script.sh
ENTRYPOINT ["/script.sh"]
CMD ["rails", "server", "-b", "0.0.0.0"]

  • COPY will copy files from to the host in the image
  • MAINTAINER is now deprecated and replaced with LABEL but can still be found in documentation. It is used to set image metadata.
  • Yum has ben used instead of APT but file structure is the same
Example 3

FROM ruby:3.2.2-alpine
LABEL maintainer="Nicolas Author"
RUN apt-get update && apt-get install -y nodejs
WORKDIR /app
COPY Gemfile* .
RUN bundle install
COPY ..
EXPOSE 3000
CMD ["rails", "server", "-b", "0.0.0.0"]

 

  • LABEL has been used instead of the deprecated MAINTAINER
  • WORKDIR sets the directory from which the application will run in the image
  • EXPOSE indicates the port to expose. In our case, this is set in our Docker-compose file.

 

 

  1. Check logs and debug

If your container restarts all the time, you can check the logs:

sudo docker logs redmine

 

It will give you the end of the logs.

To define how much of the logs to see, option --tail can be used:

sudo docker logsredmine -f --tail 1000

 

Or if you want to follow the logs as you are using the application

sudo docker logs redmine -f

This is particularly usefull when debuging a specific page loading issue.

 

To check all the log options, you can run:

docker logs --help

 

Depending on the errors observed, you will need to either:

  • correct your docker-compose.yml file
  • review your network/database connectivity
  • update/customize plugin code

 

  • Example of a database connectivity issue

 

This was because the docker-compose.yml  was calling the wrong port on the database server:

 

Here, we only need to update the docker-compose.yml file and restart the container.

 

  • Example of an issue caused by plugins installed

 

The plugin code has been pulled into the wrong directory

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

 

Cheking the plugins folders:

sudo ls -l /opt/redminedocker/plugins/
total 4
drwxr-xr-x 8 root root 4096 Oct 12 19:23 onlyoffice-redmine

 

The GIT clone has copied the files to a folder differnt from the one delcared in the plugin. The quick fix is simple:

sudo mv /opt/redminedocker/plugins/onlyoffice-redmine /opt/redminedocker/plugins/onlyoffice_redminesudo docker restart redmine

 

  •  

    The plugin installed has unmet dependencies

Trying to install Redmin SAML plugin on a newly deployed Redmine instance, we get:

Redmine::PluginRequirementError: redmine_saml plugin requires the additionals plugin

 

Checking the documentation, we see that plugin Additionals is required:

cd /opt/redminedocker/plugins/
sudo git clone https://github.com/alphanodes/additionals.gitsudo docker restart redmine

 

 

  • The plugin we’re trying to install isn’t fully compatible due to synthax/code issues with our version of Ruby or Rail

 

Installing the plugin Issue tree to help in visual ticket/issue management, we get the error:

NameError: uninitialized constant RedmineIssuesTree::VERSION
version RedmineIssuesTree::VERSION
^^^^^^^^^
Did you mean? RedmineIssuesTree::Version
Version
/usr/src/redmine/plugins/redmine_issues_tree/init.rb:7:in block in <top (required)>'<br />/usr/src/redmine/lib/redmine/plugin.rb:96:in instance_eval'
/usr/src/redmine/lib/redmine/plugin.rb:96:in register'<br />/usr/src/redmine/plugins/redmine_issues_tree/init.rb:3:in <top (required)>'

 

Checking the init.rb file for that plugin:

sudo vi redmine_issues_tree/init.rb

 

We see:

version RedmineIssuesTree::VERSION

 

Updating to the expected format, we then get another error:

Zeitwerk::NameError: expected file /usr/src/redmine/plugins/redmine_issues_tree/lib/redmine_issues_tree/version.rb to define constant RedmineIssuesTree::Version, but didn't

 

We simply need to update file redmine_issues_tree/lib/redmine_issues_tree/version.rb to declare constant "Version" instead of "VERSION" and all works fine:

 

  • All issues have been corrected but the container still reboots non-stop

If you want to restart with a clean container, you can force-delete the running container and the re-deploy from the docker-compose file:

sudo docker rm -f redmine
sudo docker-compose up -d

 

Restarting from a new container can be useful in order to reset some of the environment parameters that can be a cause of issues.

 

  1. Update application & install themes/plugins

Updating image

Our example is set to use redmine:5.0.5 but redmine:5.0.6 has since been released.

Updating an application running from a Docker-compose file is pretty straitforward:

  1. Update the docker-compose file with the new image
  2. Run:

sudo docker-compose up -d

The new image will be pulled and a new container deployed using the same parameters.

 

Note: If you use another image source, check the documentation to make sure you are using the proper parameters.
The "environment" tags are those to be used with that image.
Other Docker images for Redmine exist and use different environment parameter names for example the Bitnami Redmine or even user maintained images such as Sameersbn Docker Redmine

 

Installing themes & plugins

There are many ways themes and plugins can be installed using docker but I'll only detail the one I most commonly use.

 

In the docker-compose.yml file, volums are set as:

    volumes:
      - /opt/redminedocker/plugins:/usr/src/redmine/plugins
      - /opt/redminedocker/public/themes:/usr/src/redmine/public/themes
      - /opt/redminedocker/files:/usr/src/redmine/files

And we have an environment parameter set:

    environment:
      - "REDMINE_PLUGINS_MIGRATE=true"

 

This means that when starting up the container, Docker will call on files from the host.

To install a theme or plugin, you simply need to download the theme/plugin code in the correct folder and restart the container.

Added themes will be available and new plugins will be installed automatically.

 

Example with the Purplemine2 theme:

cd /opt/redminedocker/public/themes
sudo git clone https://github.com/mrliptontea/PurpleMine2
sudo docker restart redmine

Installed plugins will then appear in the/settings?tab=display page.

 

Example with the Redmine Dashboard plugin:

cd /opt/redminedocker/plugins/
sudo git clone https://github.com/jgraichen/redmine_dashboard.git
sudo docker restart redmine

 

Installed plugins will then appear in the /admin/plugins page.

 

Note: usually, the application is available after 30 seconds after restart.

If it is not available or the images is always restarting, simply remove the folder containing the plugin you just added.

Even though plugins are compatible and have been tested with the different Redmine versions, when using custom Redmine images or simply multiple plugins, you can find that applications parameters set for one plugin will not be compatible with another. You then need to "debug" or adapt the plugin(s) you want to use.

 

0 0 votes
Article Rating
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x
()
x