How to Install Redmine on Ubuntu 2204 & 2210¶

Run system update
To begin with, ensure that your system packages are up-to-date.

apt update && upgrade -y

Redmine is not available on the default Ubuntu 22.04 & 22.10

Therefore, to install Redmine you need to build and install it from the source.

Install Required Build Tools and Dependencies¶

To install Redmine from the source code, you need install the required build tools and dependencies.

apt install build-essential ruby-dev libxslt1-dev libmariadb-dev \
libxml2-dev zlib1g-dev imagemagick libmagickwand-dev curl \
gnupg2 bison libbison-dev libgdbm-dev libncurses-dev libncurses5-dev \
libreadline-dev libssl-dev libyaml-dev libsqlite3-dev sqlite3 -y

Install Apache HTTP Server¶

Install Apache web server and Apache modules for the Passenger, lightweight web server for Ruby.

apt install apache2 libapache2-mod-passenger

Start and enable Apache to run on system boot.

systemctl enable --now apache2

Install Ruby interpreter
Redmine version 5.0 supports Ruby 3.0.

Ruby is installed as part of the above package dependencies. To check the current version of installed Ruby;

ruby -v

ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]

Create Redmine System User¶

Create a Redmine system user that can be used to install Redmine Ruby dependencies via bundler command. Set its home directory to /opt/redmine as this is where we will install Redmine app.

useradd -r -m -d /opt/redmine -s /usr/bin/bash redmine

Add Apache web server user to Redmine group.

usermod -aG redmine www-data
Install MariaDB on Ubuntu 22.04
Run the command below to install MariaDB database server on Ubuntu 22.04

apt install mariadb-server

MariaDB is started and enabled to run on boot upon installation. If not already started, run the command below to start it;

systemctl enable --now mariadb

Run initial MariaDB database secure script to remove default databases, test tables, disable remote root login,

mysql_secure_installation

Create Redmine Database and Database User¶

Once MariaDB is installed, login as root user and create Redmine database and database user.

Replace the names of the database and the database user accordingly.

mysql -u root -p
create database redminedb;
grant all on redminedb.* to redmineuser@localhost identified by 'P@ssW0rD';

Reload privilege tables and exit the database.

flush privileges;

quit

Download and Install Redmine¶

Navigate Redmine releases page and grab Redmine tarball for the current stable release version.

You can simply download and extract the Redmine tarball to the Redmine install directory, /opt/redmine.

VER=5.0.5

curl -s https://www.redmine.org/releases/redmine-5.0.5.tar.gz | sudo -u redmine tar xz -C /opt/redmine/ --strip-components=1

Configuring Redmine
Once you have installed Redmine under the /opt/redmine directory, you can now proceed to configure it.

Create Redmine configuration file by renaming the sample configuration files as shown below;

su - redmine
cp /opt/redmine/config/configuration.yml{.example,}
cp /opt/redmine/public/dispatch.fcgi{.example,}
cp /opt/redmine/config/database.yml{.example,}

Configure Redmine Database Settings¶

Open the created Redmine database configuration setting and set the Redmine database connection details for MySQL.

Nano /opt/redmine/config/database.yml

...

production:
  adapter: mysql2
  database: redminedb
  host: localhost
  username: redmineuser
  password: "P@ssW0rD" 
  # Use "utf8" instead of "utfmb4" for MySQL prior to 5.7.7
  encoding: utf8mb4
...

Save and exit the file.

Install Redmine Ruby Dependencies
Logout as redmine user by running the exit.¶

exit

As privileged user, navigate to Redmine install directory and install the Ruby dependencies.

cd /opt/redmine

Install Bundler for managing gem dependencies.

sudo gem install bundler

Next, install the required gems dependencies as redmine user.

su - redmine

bundle config set --local path 'vendor/bundle'

bundle install

Also update the gems;

bundle update

Install updated io-wait and strscan gems;

gem install io-wait strscan webrick --user-install

Generate Secret Session Token
To prevent tempering of the cookies that stores session data, you need to generate a random secret key that Rails uses to encode them.

bundle exec rake generate_secret_token

Create Database Schema Objects
Create Rails database structure by running the command below;

Ensure you set the correct database credentials above,

RAILS_ENV=production bundle exec rake db:migrate

Once the database migration is done, insert default configuration data into the database by executing;

RAILS_ENV=production REDMINE_LANG=en bundle exec rake
redmine:load_default_data

You can safely ignore the Ruby warnings.

Configure FileSystem Permissions
Ensure that the following directories are available on Redmine directory, /opt/redmine.

• tmp and tmp/pdf
• public and public/plugin_assets
• log
• files

If they do not exist, simply create them and ensure that they are owned by the user used to run Redmine.

for i in tmp tmp/pdf public/plugin_assets; do [ -d $i ] || mkdir -p $i; 
done

chown -R redmine:redmine files log tmp public/plugin_assets

chmod -R 755 /opt/redmine

Testing Redmine Installation¶

The setup of Redmine on Ubuntu is now done. Redmine listens on TCP port 3000 by default. Hence, before running the tests, open port 3000/tcp on firewall if it is running.

exit

sudo ufw allow 3000/tcp

You can now test Redmine using WEBrick by executing the command below;

su - redmine

Add webrick to Gemfile;

echo 'gem "webrick"' >> Gemfile

Install webrick gem and test the installation;

bundle install

bundle exec rails server -u webrick -e production

Sample output;

=> Booting WEBrick
=> Rails 6.1.7.2 application starting in production http://0.0.0.0:3000
=> Run `bin/rails server --help` for more startup options
[2023-04-11 18:01:19] INFO  WEBrick 1.8.1
[2023-04-11 18:01:19] INFO  ruby 3.0.2 (2021-07-07) [x86_64-linux-gnu]
[2023-04-11 18:01:19] INFO  WEBrick::HTTPServer#start: pid=7553 port=3000

Navigate to the browser and enter the address, http://server-IP-or-Hostname:3000. Replace the server-IP-or-Hostname accordingly.

If all is well, you should land on Redmine web user interface.

Configure Apache
Now that you have confirmed that Redmine is working as expected, proceed to configure Apache to server Redmine.

Create Redmine Apache VirtualHost configuration file.

exit

sudo nano /etc/apache2/sites-available/redmine.conf

cat > /etc/apache2/sites-available/redmine.conf << 'EOL'
Listen 3000
<VirtualHost *:3000>
    ServerName redmine.kifarunix-demo.com
    RailsEnv production
    DocumentRoot /opt/redmine/public

    <Directory "/opt/redmine/public">
            Allow from all
            Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/redmine_error.log
        CustomLog ${APACHE_LOG_DIR}/redmine_access.log combined
</VirtualHost>
EOL

Save and exit the file by pressing Ctrl + X, then Y, then Enter.

Check Apache configuration for errors.

apachectl configtest

Should See: Syntax OK
Ensure that Passenger module is loaded;

apache2ctl -M | grep -i passenger

Should See: assenger_module (shared)

If not enabled, run the command below to enable it.

a2enmod passenger

Should See: Enable Redmine site.

sudo a2ensite redmine

Disable default site;

a2dissite 000-default.conf

Reload Apache

sudo systemctl restart apache2

Check to ensure that Redmine is now listening on port 3000.

sudo lsof -i :3000

Should SEE this...

COMMAND  PID     USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
apache2 7630     root    6u  IPv6  48985      0t0  TCP *:3000 (LISTEN)
apache2 7645 www-data    6u  IPv6  48985      0t0  TCP *:3000 (LISTEN)
apache2 7646 www-data    6u  IPv6  48985      0t0  TCP *:3000 (LISTEN)

Access Redmine on Browser¶

Next, you can now access and sign in to Redmine on browser using the address http://server-IP-address:3000

Default credentials: admin:admin.