For the old-school crew who want one reference place to getting Redmine up and running, this guide will walk through the maze of twisty little passages, all alike.
These flexible instructions will get an up to date, robust, secure installation going.
- Ubuntu 24.04 LTS - a mature Ubuntu version with long term support
- MySQL - the database
- Ruby - the technology on which Redmine runs, installed using RVM to manage the ruby version and have access to up to date components
- Phusion Passenger- the application container in which to run Redmine
- nginx - the web server within which Redmine runs
Install MySQL
Install MySQL. For this step, relying on the Ubuntu packages is fine.
sudo apt-get install -y mysql-server libmysqlclient-dev
Connect to the mysql service (sudo mysql) and create the database and provide access to the redmine database user:
sudo mysql
CREATE DATABASE redmine CHARACTER SET utf8mb4;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
If this is just a test system, move onto the Ruby Installation section.
MySQL Data Disk (Optional)
For production systems, a separate data disk should be used
rather that storing data on the same partition as the root system. Stop the database service and then migrate the data directory.
sudo systemctl stop mysql
sudo rsync -avzh /var/lib/mysql /websvc
(Replace /websvc with the top level of the new data directory; rsync preseves all the correct permissions)
Modify the data directory configuration in MySQL:
sudo vim /etc/mysql/mysql.conf.d/mysqld.cnf
#datadir = /var/lib/mysql #old location
datadir = /websvc/mysql #new location
Update AppArmor, otherwise the mysql process won't start.
sudo vim /etc/apparmor.d/tunables/alias
alias /var/lib/mysql/ -> /websvc/mysql/,
Don't forget the extra comma; it is not a typo!
Now restart both services. If everything has been done correctly, they will start without error.
sudo systemctl reload apparmor
sudo systemctl start mysql
Log into the database system to ensure everything looks okay:
sudo mysql
SELECT @@datadir;
The updated data directory should be evident.
Ruby Installation
Many methods exist to install Ruby. Unfortunately, the most convenient using apt-get will leave the system many versions behind, which means many plugins for redmine, and parts of redmine itself, will be unsupported and likely break.
RVM is the recommended method to provide clean management of ruby
versions.
sudo apt-get update
sudo apt-get install -y curl gnupg build-essential
sudo gpg --keyserver hkp://keys.gnupg.net --recv-keys
409B6B1796C275462A1703113804BB82D39DC0E3
7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | sudo bash -s stable
sudo usermod -a -G rvm `whoami`
Redmine 6.1 requires Ruby 3.2, 3.3, or 3.4.
rvm install 3.4.7
rvm --default use ruby-3.4.7
gem install bundler --no-document
Ruby should now be installed.
ruby -v
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [x86_64-linux]
Note: once setup,
each user of RVM needs to be added to the rvm group.
sudo usermod -a -G rvm username
Phusion Passenger Installation
Many options exist for application containers. Phusion has a Passenger-nginx combo that is is purpose built for Ruby and Rails applications. Installation instructions are pulled from the Phusion site.
First step is to install nginx, if it is not already present.
Then set up the Passenger repository:
# Install PGP key and add HTTPS support for APT
sudo apt-get install -y dirmngr gnupg apt-transport-https ca-certificates curl
curl https://oss-binaries.phusionpassenger.com/auto-software-signing-gpg-key.txt | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/phusion.gpg >/dev/null
# Add Passenger APT repository
sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger noble main > /etc/apt/sources.list.d/passenger.list'
sudo apt-get update
sudo apt-get install -y libnginx-mod-http-passenger
And finally move the configuration files to the correct places:
if [ ! -f /etc/nginx/modules-enabled/50-mod-http-passenger.conf ]; then sudo ln -s /usr/share/nginx/modules-available/mod-http-passenger.load /etc/nginx/modules-enabled/50-mod-http-passenger.conf ; fi
sudo ls /etc/nginx/conf.d/mod-http-passenger.conf
Nginx can now be restarted and should have Passenger running within.
sudo service nginx restart
Optionally, the following health checks can be run.
sudo /usr/bin/passenger-config validate-install
sudo /usr/sbin/passenger-memory-stats
Create a Redmine Service Account
Before doing too much with Ruby, create a redmine service account. The home directory is located where redmine is going to be installed - for production systems this should be on a separate partition.
In this example /websvc/redmine is where Redmine will be installed. This directory will be created when the user is created.
sudo adduser --system --shell /bin/bash --gecos 'Redmine
Administrator' --group --disabled-password --home /websvc/redmine redmine; sudo
usermod -a -G rvm redmine
Give the account sudo
privileges (temporarily).
sudo visudo
redmine
ALL=(ALL) NOPASSWD:ALL
As of Ubuntu 21, the user's home directory is locked down such that nginx will not be able to access the Redmine installation. This one step will save many minutes and/or hours of troubleshooting.
sudo su - redmine # should result in being in the redmine installation directory
chmod 755 .
Whew. Like a hero that doesn't show up until the third reel of a movie, Redmine is finally on the scene.
Install Redmine with the Redmine Service Account
As the redmine user, and in the redmine home directory (/websvc/redmine), pull down the latest stable release.
wget https://www.redmine.org/releases/redmine-6.1.0.tar.gz
tar xvfz
ln -s redmine-6.1.0 redmine
rm redmine-6.1.0.tar.gz
Configure the Redmine mysql Connection
As the redmine service account, update the production database entry with the account connection information.
cd redmine
cp -pR config/database.yml.example config/database.yml
vim config/database.yml
database: redmine
host: localhost
username: redmine
password: "yourpassword"
Install Redmine Ruby Requirements
As the redmine service account, adding the Redmine gems dependencies.
bundle config set --local without 'development test'
bundle install
If versions and such match these instructions, the bundle install should go clean:
Bundle complete! 52 Gemfile dependencies, 94 gems now installed.
If versions are different or new features are needed, some iteration may be needed to build and install the gems. This seems to be a "normal" task for ruby administrators. Apply google-fu or a chatbot and iterate.
Generate the token:
bundle exec rake generate_secret_token
Then initialize the database:
RAILS_ENV=production bundle exec rake db:migrate
Optionally load default data as well:
RAILS_ENV=production bundle exec rake redmine:load_default_data
Update nginx to Run Redmine
More configuration will be needed to SSL-ize the system and lock it down. But for now, these steps will get the Redmine site up and running.
These steps do not need to be run as the redmine user.
Confirm the Ruby runtime location, the result will be used in a later step.
passenger-config about ruby-command
To use in Nginx : passenger_ruby /usr/local/rvm/gems/ruby-3.4.7/wrappers/ruby
Update the root location and add passenger configuration. The assumption is your redmine root location is also on the /websvc partition.
sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.orig
sudo vim /etc/nginx/sites-available/default
root /websvc/redmine/redmine/public; #installation location
passenger_enabled on; #turn on application container
passenger_ruby /usr/local/rvm/gems/ruby-3.4.7/wrappers/ruby; #Ruby runtime
client_max_body_size 10m; # Max attachment size allowed
Then to prevent a mess of 404 errors, comment out the location entry. Missing this step results in only getting a 404 and nothing else.
#location / {
# First attempt to serve request as file, then
# as directory, then fall back to displaying a 404.
#try_files $uri $uri/ =404;
#}
Now everything should be ready to start. This is done by restarting nginx.
sudo service nginx restart
Monitor the following logs to ensure things start clean:
tail -f /var/log/nginx/error.log
tail -f /data/redmine/redmine/log/production.log
Congratulations, the redmine site should now be up and available.
Initial login is admin : admin.
Clean up
Remove sudo privileges from the redmine account. Move the site to HTTPS, ideally using the excellent Let's Encrypt service.
Links of Interest
General Redmine installation
Always a good place to review the latest information on
generic Redmine installations.
https://www.redmine.org/projects/redmine/wiki/RedmineInstall
Phusion Passenger installation
https://www.phusionpassenger.com/docs/tutorials/deploy_to_production/installations/oss/ownserver/ruby/nginx/
No comments:
Post a Comment