Install Redmine with Nginx, Puma, and MariaDB/MySQL on Ubuntu 14.04

Redmine Installation

Install Redmine on a LEMP stack

On a whim I decided to try installing Redmine, the popular project management application written in Ruby on Rails. I don’t have any experience with Ruby, but there don’t seem to be any comparable open source Python options out there. Since I don’t plan on using Ruby for anything aside from Redmine, I ended up installing many pieces under a local user to keep things tidy.

For this tutorial I’m using an Ubuntu 14.04 server where I’ve previously installed Nginx and MariaDB. If you’re looking for more information on setting up Nginx and MariaDB, check out an earlier post on deploying a LEMP stack.

Once Redmine has been installed, you may be interested in configuring Redmine’s outgoing email with SMTP or Sendmail and setting up Redmine’s incoming email.

Package Updates and Dependencies

Update your package lists and upgrade any existing packages.

sudo apt-get update
sudo apt-get -y upgrade

Install a few dependencies to make sure we can compile Ruby and use the necessary gems.
sudo apt-get install autoconf git subversion curl bison \
imagemagick libmagickwand-dev build-essential libmariadbclient-dev libssl-dev \
libreadline-dev libyaml-dev zlib1g-dev python-software-properties

Redmine Local User

Create a new user for Redmine. We’ll be installing Ruby and Redmine into that user’s home directory so go ahead and switch to that user.

sudo adduser --disabled-login --gecos 'Redmine' redmine
sudo su - redmine

Install Ruby Environment

I used rbenv and the plugin ruby-build to manage my Ruby installation and gems. They’re can be cloned from GitHub.

git clone git:// .rbenv
git clone git:// ~/.rbenv/plugins/ruby-build

Add rbenv to your shell’s path. Restart your shell to enable access to the command.

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
exec $SHELL -l

Now install Ruby. This will take a while so be patient.

rbenv install 2.1.2

Once installed, set it as the global Ruby version and test the command. You should see something like ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-linux].

rbenv global 2.1.2
ruby -v

Install Redmine

Checkout the source for Redmine, add some directories, and adjust the permissions.

svn co redmine
cd redmine
mkdir -p tmp/pids tmp/sockets public/plugin_assets
chmod -R 755 files log tmp public/plugin_assets

Create the Puma configuration file.

nano config/puma.rb
#!/usr/bin/env puma

# start puma with:
# RAILS_ENV=production bundle exec puma -C ./config/puma.rb

application_path = '/home/redmine/redmine'
directory application_path
environment 'production'
daemonize true
pidfile "#{application_path}/tmp/pids/"
state_path "#{application_path}/tmp/pids/puma.state"
stdout_redirect "#{application_path}/log/puma.stdout.log", "#{application_path}/log/puma.stderr.log"
bind "unix://#{application_path}/tmp/sockets/redmine.sock"

You can also grab the Puma configuration from GitHub.

curl -Lo /home/redmine/redmine/config/puma.rb

Configure MariaDB/MySQL

Connect to MariaDB/MySQL to create a Redmine database and user.

mysql -u root -p
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';

Copy the database configuration example and update the production server with the new credentials.

cp config/database.yml.example config/database.yml
nano config/database.yml
  adapter: mysql2
  database: redmine
  host: localhost
  username: redmine
  password: "YOURPASSWORD"
  encoding: utf8

Install Gems

echo "gem: --no-ri --no-rdoc" >> ~/.gemrc
echo -e "# Gemfile.local\ngem 'puma'" >> Gemfile.local
gem install bundler
rbenv rehash
bundle install --without development test

Generate Token and Prepare Database

Generate random key for encoding cookies, create database structure, and insert default configuration data.

rake generate_secret_token
RAILS_ENV=production rake db:migrate
RAILS_ENV=production rake redmine:load_default_data

Test Installation

Run a test with WEBrick to make sure Redmine is working. Open the URL http://<YOURSERVER>:3000 in your browser and confirm that Redmine loads successfully.
ruby script/rails server webrick -e production
If you need to change the default port, just append -p followed by desired port number.
ruby script/rails server webrick -e production -p5000
Use CTRL+C to stop WEBrick. At this point, you're done issuing commands as your local Redmine user. Go back to your own user account by typing exit.

Init Configuration

If the tests were successful, add an init script to start Redmine automatically and allow you to manage the process using service. Be sure you've exited your Redmine user, as the rest of the steps require root access.
sudo nano /etc/init.d/redmine
#! /bin/sh
# Provides:          redmine
# Required-Start:    $local_fs $remote_fs $network $syslog
# Required-Stop:     $local_fs $remote_fs $network $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Starts redmine with puma
# Description:       Starts redmine from /home/redmine/redmine.

# Do NOT "set -e"


SET_PATH="cd $APP_ROOT; rbenv rehash"
DAEMON="bundle exec puma"
DAEMON_ARGS="-C $APP_ROOT/config/puma.rb -e $RAILS_ENV"
DESC="Redmine Service"

cd $APP_ROOT || exit 1

sig () {
        test -s "$PIDFILE" && kill -$1 `cat $PIDFILE`

case $1 in
        sig 0 && echo >&2 "Already running" && exit 0
        su - $APP_USER -c "$CMD"
        sig QUIT && exit 0
        echo >&2 "Not running"
        sig USR2 && echo "Restarting" && exit 0
        echo >&2 "Couldn't restart"
        sig 0 && echo >&2 "Running " && exit 0
        echo >&2 "Not running" && exit 1
        echo "Usage: $SCRIPTNAME {start|stop|restart|status}" >&2
        exit 1

You can also grab the Redmine/Puma init script from GitHub.
sudo curl -Lo /etc/init.d/redmine
sudo chmod +x /etc/init.d/redmine
sudo update-rc.d redmine defaults
Go ahead and and start the redmine service you just added. In the future, puma will load Redmine automatically on boot.
service redmine start

Nginx Server Block

Finally, just set up the Nginx server block with a Redmine/Puma upstream and the appropriate proxy settings.
sudo nano /etc/nginx/sites-available/redmine
upstream puma_redmine {
  server unix:/home/redmine/redmine/tmp/sockets/redmine.sock fail_timeout=0;

server {
  listen 80;
  root /home/redmine/redmine/public;

  location / {
    try_files $uri/index.html $uri.html $uri @ruby;

  location @ruby {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP  $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
    proxy_read_timeout 300;
    proxy_pass http://puma_redmine;
Yes, the Nginx configuration is on GitHub, too.
sudo curl -Lo /etc/nginx/sites-available/redmine
Link the config to sites-enabled and restart Nginx and you're done!
sudo ln -s /etc/nginx/sites-available/redmine /etc/nginx/sites-enabled/redmine
sudo service nginx restart
Log into Redmine with the default account admin/admin. Visit My Account to change the default password. You can change the default account's username by visiting the Users section under Administration. You may also want to check out:

25 responses to “Install Redmine with Nginx, Puma, and MariaDB/MySQL on Ubuntu 14.04”

  1. Great article, thanks for providing direction on this configuration.

    Unfortunately I’m running into issues launching Redmine via Puma under the redmine credentials. The key problem is likely my unfamiliarity with account management on Linux. I’d expect that somewhere in the directions we’d have set a password for the redmine user but by launching sudo su – redmine we get around this aspect. However, when I try to run nginx after finishing the guide I receive a “502 Bad Gateway” response. After some digging I switched the nginx config over to use the webrick instance on port 3000 and confirmed that nginx is working great and the issue is caused by problems launching the redmine service. If I bounce that service it prompts for a password which I assume is for the redmine account to which I have no password. If I try to launch the service via sudo it reports that Puma isn’t installed, which makes since given the user I’m attempting to then run as. So, my issue seems to be I don’t know how to start or configure the redmine service and so far haven’t had good luck on Google making sense of the magic behind sudo su – as it relates to this scenario.

    Any details or insight that you can provide would be greatly appreciated.


    • Hi John,

      In this configuration, the redmine account I created did not have a password because that user is never intended to actually log in. Puma is loaded by the system and then switched over the redmine user so the user’s password is not required.

      If you can load Redmine using webrick, you’re almost there. It sounds like there’s something wrong with the Nginx configuration.

      Is Puma running on its own? When it’s running does /home/redmine/redmine/tmp/sockets/redmine.sock exist? Are you using a relatively recent version of Ubuntu?

      • I wrote up a long description of what I’ve been seeing and the more I described the problem the closer I got to the issue. I was being misdirected into thinking this was an authentication problem because it would repeatedly prompt for an su password in both the redmine and my personal user contexts. As I continued to try and write up the details I started trying different commands to report how it would behave and why the /etc/init.d/redmine script wouldn’t run.

        In the end the problem came down to me thinking I had Puma installed because I followed the instructions to add and install the puma gem via Bundler. When I manually tried running the command the /etc/init.d/redmine executes during “start”

        bundle exec puma -C /home/redmine/redmine/config/puma.rb -e production

        I finally realized that Puma wasn’t actually installed when I ran the prescribed bundle install steps. If I cat Gemfile.local in the redmine root directory I see the following:

        # Gemfile.localngem ‘puma’

        That doesn’t look too promising and I assumed those were supposed to be separate lines so I added gem ‘puma’ to the normal Gemfile and finally got it installed. Afterward I was able to execute the original “bundler exec puma” command without errors and “sudo service redmine start/stop” actions now run without the confusing and problematic authentication errors.

        Thanks again for all the help

        • Ah! So there’s supposed to be a backslash before the n in command used to create the Gemfile.local. For whatever reason, it was stripped out of the version posted here. I’ve updated the article to restore the missing character.

          The line should be:
          echo -e "# Gemfile.local\ngem 'puma'" >> Gemfile.local

          Thanks for finding this omission!

  2. Hi, i followed this tutorial and the installation went fine.

    except i cannot access the redmine. In nginx error.log is this entry:
    2014/12/01 15:38:41 [error] 10183#0: *1 connect() to unix:/home/redmine/redmine/tmp/sockets/redmine.sock failed (111: Connection refused) while connecting to upstream,

    i guess its some kind of permission problem, but i don’t know where to look and how to fix it.

    many thanks for any help

    • Hi Martin,

      Is Puma running and does the redmine socket exist (redmine.sock)? If so, does Nginx have permission to access redmine.sock?

      I’d check the permissions all the way along the path. Run the command below and paste the results.
      namei -l home/redmine/redmine/tmp/sockets/redmine.sock

      Here are the results from my own installation.

      f: /home/redmine/redmine/tmp/sockets/redmine.sock
      drwxr-xr-x root root /
      drwxr-xr-x root root home
      drwxr-xr-x redmine redmine redmine
      drwxrwxr-x redmine redmine redmine
      drwxr-xr-x redmine redmine tmp
      drwxr-xr-x redmine redmine sockets
      srwxrwxrwx redmine redmine redmine.sock

  3. Thanks a lot for this how-to!
    Just want to add that I’ve got error after executing “bundle install –without development test”

    Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    /home/redmine/.rbenv/versions/2.1.2/bin/ruby extconf.rb
    checking for Ruby version >= 1.8.5... yes
    checking for gcc... yes
    checking for Magick-config... yes
    checking for ImageMagick version >= 6.4.9... *** extconf.rb failed ***
    Could not create Makefile due to some reason, probably lack of necessary
    libraries and/or headers. Check the mkmf.log file for more details. You may
    need configuration options.

    Provided configuration options:
    extconf.rb:154:in ``': No such file or directory - convert (Errno::ENOENT)
    from extconf.rb:154:in `block in '
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:918:in `block in checking_for'
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:351:in `block (2 levels) in postpone'
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:321:in `open'
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:351:in `block in postpone'
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:321:in `open'
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:347:in `postpone'
    from /home/redmine/.rbenv/versions/2.1.2/lib/ruby/2.1.0/mkmf.rb:917:in `checking_for'
    from extconf.rb:151:in `'

    extconf failed, exit code 1

    Gem files will remain installed in /home/redmine/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/rmagick-2.13.4 for inspection.
    Results logged to /home/redmine/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/extensions/x86_64-linux/2.1.0-static/rmagick-2.13.4/gem_make.out
    An error occurred while installing rmagick (2.13.4), and Bundler cannot continue.
    Make sure that `gem install rmagick -v '2.13.4'` succeeds before bundling.

    So I had to install imagemagick first (‘sudo apt-get install imagmagick’)

    • I believe libmagickwand-dev used to satisfy the requirement so I did not have to install imagemagick when I initially wrote this tutorial. That’s no longer sufficient so I’ve updated the tutorial to include imagemagick.

      While walking through this tutorial on a couple Ubuntu 14.04 x64 servers I found a few other changes and updated those as well.

  4. This is my server config:

    upstream puma_redmine {
    server unix:/home/redmine/redmine/tmp/sockets/redmine.sock fail_timeout=0;

    server {
    listen 3000;
    root /home/redmine/redmine/public;

    location / {
    try_files $uri/index.html $uri.html $uri @ruby;

    location @ruby {
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_redirect off;
    proxy_read_timeout 300;
    proxy_pass http://puma_redmine;

    But, when i go to I get an “502 Bad Gateway” what might be wrong?

    • It’s very possible that puma isn’t running yet.
      ps aux |grep puma

      Just start it using service this time. In the future it will start automatically when the machines boots.
      service redmine start

  5. Thanks for the how to,

    I have Puma installed as is see it on the gem list output, but when i try and do service puma start it just says that the service does not exist.

    Therefore i cannot access the Redmine installation.

  6. Thanks for your sharing, this article is the most useful that I google.
    I can visit my redmine for webBrick.

    But unfortunate, when I try “service puma start” at my own account, it always show “puma: unrecognized service”.
    Anyway, I still finish all your steps, then reboot, then I use “ps aux|grep puma”, the console prompt:
    josephw+ 4724 0.0 0.0 4680 832 pts/13 S+ 00:58 0:00 grep –color=auto puma

    BTW, I use vmplayer with a clean ubuntu14_04 Desktop, 32bit.

    Any suggestion would be appreciate.

  7. James, thanks again for you guide — I’m using it very often (for vagrant image, plugin tests etc).
    Now I’m trying to update to 2.6, and I noticed, that you’d created “plugin_assets” directory, but I haven’t found, how did you use it. Can you explain?

    • Hi there,

      That directory is used by plugins and wasn’t originally created by default. It appears to be included now, so creating it shouldn’t be necessary but the documentation still has the user adjust the permissions.

      7. Setting up permissions (Windows users have to skip this section)

      The user who runs Redmine must have write permission on the following subdirectories: files, log, tmp & public/plugin_assets.

      Assuming you run Redmine with a user named "redmine":
      sudo chown -R redmine:redmine files log tmp public/plugin_assets
      sudo chmod -R 755 files log tmp public/plugin_assets

  8. Dude! I have no words to describe how helpful this article was for me! Actually, I’ve tried several instructions to install redmine on debian with nginx, and spent couple of weeks trying to get things working. But alas!

    And now, finally, redmine works great! Thank you! Thank you! Thank you!

  9. Hey, thx a lot for this page.
    I followed all your instructions but i have a 502 bad gateway on my front. The log says : […] sockets/redmine.sock failed […]
    Actually there is no file redmine.sock in the sockets dir.
    I checked the other comments and my permissions are the same than you :

    f: /home/redmine/redmine/tmp/sockets/redmine.sock
    drwxr-xr-x root root /
    drwxr-xr-x root root home
    drwxr-xr-x redmine redmine redmine
    drwxrwxr-x redmine redmine redmine
    drwxr-xr-x redmine redmine tmp
    drwxr-xr-x redmine redmine sockets
    srwxrwxrwx redmine redmine redmine.sock

    This my “service redmine status” :

    ● redmine.service – LSB: Starts redmine with puma
    Loaded: loaded (/etc/init.d/redmine)
    Active: active (exited) since …
    Docs: man:systemd-sysv-generator(8)
    Process: 10787 ExecStop=/etc/init.d/redmine stop (code=exited, status=0/SUCCESS)
    Process: 10790 ExecStart=/etc/init.d/redmine start (code=exited, status=0/SUCCESS)

    … su[10791]: Successful su for redmine by root
    … su[10791]: + ??? root:redmine
    … su[10791]: pam_unix(su:session): session opened for user redmine by (uid=0)
    … redmine[10790]: Puma starting in single mode…
    … redmine[10790]: * Version 2.12.2 (ruby 2.1.2-p95), codename: Plutonian Photo Shoot
    … redmine[10790]: * Min threads: 0, max threads: 16
    … redmine[10790]: * Environment: production
    … redmine[10790]: * Daemonizing…
    … systemd[1]: Started LSB: Starts redmine with puma.
    … systemd[1]: Started LSB: Starts redmine with puma.

    Any idea ?
    Cheers & thx

  10. Hi James,

    thanks for your guide. After creating the service in /etc/init.d/redmine Iam not able to start redmine via service command.

    # service redmine start
    -> No passwd entry for user ‘redmine

    Do you have a solution for this? Which pw is needed?

  11. I was also prompted for a password when I run:

    “$ service redmine start”

    I played around with the account settings but eventually gave up and moved on. If I use sudo I could run the command no problem and on startup it seems like everything starts as it should so I’m not concerned at all.

    Thank you so much for your tutorial, it is perfect.

Leave a Reply

Your email address will not be published. Required fields are marked *