Installing Redmine on VPS for Project Management

Configuration

After installing the main components, you need to configure them for stable and secure Redmine operation. This includes setting up Nginx as a reverse proxy, running Puma as a system service, and enabling HTTPS.

1. Configuring Puma as a System Service (systemd)

To ensure Redmine starts automatically when the server boots and runs in the background, we will configure Puma as a systemd service.

Create a service file for Puma:

sudo nano /etc/systemd/system/redmine.service # Create new service file

Insert the following content, replacing redmineuser with your username and /var/www/redmine with the path to your Redmine installation:

[Unit]
Description=Puma HTTP Server for Redmine
After=network.target postgresql.service

[Service]
Type=simple
User=redmineuser
Group=redmineuser
WorkingDirectory=/var/www/redmine
Environment=RAILS_ENV=production
ExecStart=/home/redmineuser/.rvm/bin/rvm-auto-ruby bundle exec puma -C /var/www/redmine/config/puma.rb
ExecReload=/bin/kill -s HUP $MAINPID
TimeoutSec=15
RestartSec=2
Restart=on-failure

[Install]
WantedBy=multi-user.target

Save and close the file.

Now, create the Puma configuration file config/puma.rb:

nano /var/www/redmine/config/puma.rb # Create Puma configuration file

Insert the following content:

# config/puma.rb
# Replace 'redmineuser' with your username
# Replace '/var/www/redmine' with the path to your Redmine installation

workers Integer(ENV['WEB_CONCURRENCY'] || 2)
threads_count = Integer(ENV['RAILS_MAX_THREADS'] || 5)
threads threads_count, threads_count

rackup DefaultRackup
port        ENV['PORT']     || 3000
environment ENV['RACK_ENV'] || 'production'

pidfile    "/var/www/redmine/tmp/pids/puma.pid"
state_path "/var/www/redmine/tmp/pids/puma.state"
stdout_redirect "/var/www/redmine/log/puma.stdout.log", "/var/www/redmine/log/puma.stderr.log", true

# On workers boot
on_worker_boot do
  ActiveRecord::Base.establish_connection if defined?(ActiveRecord)
end

# Allow puma to be restarted by rails restart command.
plugin :tmp_restart

Save and close the file.

Reload systemd, enable, and start the Redmine service:

sudo systemctl daemon-reload           # Reload systemd configuration
sudo systemctl enable redmine.service  # Enable Redmine service autostart
sudo systemctl start redmine.service   # Start Redmine service
sudo systemctl status redmine.service  # Check service status

Ensure that the service is running and free of errors. The output should show "active (running)" in green.

2. Configuring Nginx as a Reverse Proxy

Install Nginx if it's not already installed:

sudo apt install nginx -y # Install Nginx

Create a new Nginx configuration file for Redmine:

sudo nano /etc/nginx/sites-available/redmine.conf # Create Nginx configuration file

Insert the following content, replacing your_domain.com with your domain:

upstream redmine {
    server unix:///var/www/redmine/tmp/sockets/puma.sock fail_timeout=0;
    # Or, if Puma listens on a TCP port:
    # server 127.0.0.1:3000;
}

server {
    listen 80;
    server_name your_domain.com; # Replace with your domain
    return 301 https://$host$request_uri; # Redirect HTTP to HTTPS
}

server {
    listen 443 ssl http2;
    server_name your_domain.com; # Replace with your domain

    ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem; # Will be created by Certbot
    ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem; # Will be created by Certbot
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:10m;
    ssl_session_tickets off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
    ssl_prefer_server_ciphers on;

    root /var/www/redmine/public; # Path to Redmine's public directory

    access_log /var/log/nginx/redmine_access.log;
    error_log /var/log/nginx/redmine_error.log;

    location / {
        try_files $uri @redmine;
    }

    location @redmine {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_pass http://redmine; # Use upstream redmine
    }

    error_page 500 502 503 504 /500.html;
    client_max_body_size 100M; # Maximum upload file size
    keepalive_timeout 10;
}

Save and close the file. Activate the configuration by creating a symbolic link and removing the default one:

sudo ln -s /etc/nginx/sites-available/redmine.conf /etc/nginx/sites-enabled/ # Create symbolic link
sudo rm /etc/nginx/sites-enabled/default # Remove default Nginx configuration
sudo nginx -t                          # Test Nginx configuration syntax
sudo systemctl restart nginx           # Restart Nginx

If Puma is configured for a socket, you need to add the line bind "unix:///var/www/redmine/tmp/sockets/puma.sock" to config/puma.rb and ensure that the tmp/sockets directory exists and has the correct permissions.

mkdir -p /var/www/redmine/tmp/sockets
chmod 777 /var/www/redmine/tmp/sockets # Temporarily for testing, can be restricted later

3. Configuring TLS/HTTPS with Certbot

It is highly recommended to use HTTPS to secure traffic. We will use Certbot to obtain free SSL/TLS certificates from Let's Encrypt.

sudo apt install certbot python3-certbot-nginx -y # Install Certbot and Nginx plugin
sudo certbot --nginx -d your_domain.com           # Obtain and install certificate (replace domain)

Certbot will automatically modify your Nginx configuration to use HTTPS and set up automatic certificate renewal. Follow the on-screen instructions. Ensure that your domain already points to your VPS's IP address.

4. Verifying Functionality

Open your domain (https://your_domain.com) in a browser. You should see the Redmine login page. By default, the username is: admin, password: admin. Be sure to change it upon first login.

You can also check availability using curl:

curl -I https://your_domain.com # Check HTTP headers

Ensure that the HTTP status is 200 OK. If you encounter issues, check the Nginx logs (/var/log/nginx/error.log) and Puma/Redmine logs (/var/www/redmine/log/puma.stderr.log or /var/www/redmine/log/production.log).

Backups and Maintenance

Regular backups and timely maintenance are critically important for any production system, including Redmine. This will help avoid data loss and ensure stable operation.

1. What to back up

For a full Redmine recovery, you will need three main components:

1. Redmine Database: Contains all tasks, projects, users, settings, and other structured data.
2. files Directory: Stores all attached files, images, and documents uploaded by users.
3. Redmine Configuration Files: Key files such as config/database.yml, config/configuration.yml (for mail settings and other options), and config/initializers/secret_token.rb.

2. Simple Auto-Backup Script

Let's create a simple Bash script that will back up these components. Create a directory for backups and the script itself.

sudo mkdir -p /var/backups/redmine # Create directory for storing backups
sudo chown redmineuser:redmineuser /var/backups/redmine # Change owner
nano /home/redmineuser/redmine_backup.sh # Create backup script

Insert the following content into the script, replacing redmine_user, redmine_db, /var/www/redmine, and /var/backups/redmine with your own values.

#!/bin/bash

# Variables
DB_USER="redmine_user"
DB_NAME="redmine_db"
REDMINE_ROOT="/var/www/redmine"
BACKUP_DIR="/var/backups/redmine"
TIMESTAMP=$(date +%Y%m%d%H%M%S)

# Create directory for current backup
CURRENT_BACKUP_DIR="$BACKUP_DIR/$TIMESTAMP"
mkdir -p "$CURRENT_BACKUP_DIR"

echo "Starting Redmine backup to $CURRENT_BACKUP_DIR..."

# 1. PostgreSQL database backup
echo "Dumping database..."
sudo -u postgres pg_dump -Fc "$DB_NAME" > "$CURRENT_BACKUP_DIR/redmine_db.dump"
if [ $? -eq 0 ]; then
    echo "Database dump successfully created."
else
    echo "Error creating database dump."
fi

# 2. Backup of the files directory
echo "Copying files..."
rsync -a "$REDMINE_ROOT/files" "$CURRENT_BACKUP_DIR/"
if [ $? -eq 0 ]; then
    echo "Files successfully copied."
else
    echo "Error copying files."
fi

# 3. Copying configuration files
echo "Copying configuration files..."
cp "$REDMINE_ROOT/config/database.yml" "$CURRENT_BACKUP_DIR/"
cp "$REDMINE_ROOT/config/configuration.yml" "$CURRENT_BACKUP_DIR/"
cp "$REDMINE_ROOT/config/initializers/secret_token.rb" "$CURRENT_BACKUP_DIR/"
if [ $? -eq 0 ]; then
    echo "Configuration files successfully copied."
else
    echo "Error copying configuration files."
fi

# 4. Deleting old backups (e.g., older than 7 days)
echo "Deleting old backups (older than 7 days)..."
find "$BACKUP_DIR" -maxdepth 1 -mtime +7 -exec rm -rf {} \;
echo "Backup completed."

Make the script executable:

chmod +x /home/redmineuser/redmine_backup.sh # Make the script executable

3. Setting up Cron for Automatic Backup

Add the script to the Cron scheduler so it runs automatically, for example, daily at 3:00 AM.

crontab -e # Open crontab for the current user

Add the following line to the end of the file:

0 3 * * * /home/redmineuser/redmine_backup.sh >> /var/log/redmine_backup.log 2>&1

This line means: "Every day at 3 hours 0 minutes, run the script and redirect its output to a log file."

4. Where to Store Backups

Storing backups on the same server as the production system is risky. If the server fails, you will lose both the system and the backups. It is recommended to use external storage:

• S3-compatible storage: Services like AWS S3, Backblaze B2, DigitalOcean Spaces. You can use utilities like s3cmd or rclone for automatic backup uploads.
• Separate VPS: Rent a small VPS exclusively for backup storage and synchronize them there via SSH/rsync.
• Local NAS/server: If you have your own infrastructure, you can set up synchronization with it.

For example, to send to S3, you can add a line to the script that uses aws cli or rclone after creating the local backup.

5. Updates: Rolling vs. Maintenance Window

Keeping Redmine and underlying software up to date is important for security and new features.

• OS and System Package Updates: It is recommended to apply security updates regularly (once a week/month) during a "maintenance window" when server load is minimal.

  
  sudo apt update && sudo apt upgrade -y # Update system packages
  sudo apt autoremove -y # Remove unnecessary packages
  

• Ruby Updates: Ruby updates must be thoroughly tested as they can affect Redmine's operation. Use RVM to install a new Ruby version, test Redmine with it, then switch.
• Redmine Updates:
  • Always perform a full backup before updating Redmine.
  • Stop the Redmine service (sudo systemctl stop redmine.service).
  • Download the new Redmine version, unpack it, copy files (except files, config, plugins).
  • Update gems (bundle install --without development test).
  • Run database migrations (bundle exec rake db:migrate RAILS_ENV=production).
  • Start the Redmine service (sudo systemctl start redmine.service).

Plan Redmine updates as separate projects, preferably testing them on a staging server first.

Troubleshooting + FAQ

This section contains answers to frequently asked questions and solutions to common problems that may arise during Redmine installation and operation on a VPS.

1. Redmine doesn't start or gives a 502 Bad Gateway error with Nginx. What to check?

A 502 Bad Gateway error usually means that Nginx cannot communicate with the backend application (Puma). This can be caused by several reasons:

• Puma not running: Check the status of the Puma service: sudo systemctl status redmine.service. If it's inactive, check Puma logs: journalctl -u redmine.service or /var/www/redmine/log/puma.stderr.log.
• Incorrect Nginx configuration: Make sure that proxy_pass in your Nginx configuration points to the correct Puma address/socket (e.g., http://127.0.0.1:3000 or unix:///var/www/redmine/tmp/sockets/puma.sock). Check Nginx syntax: sudo nginx -t.
• Permission issues: Ensure that the Nginx user (usually www-data) has access to the Puma socket if you are using a socket.
• Database issues: If Puma starts but immediately crashes, Redmine might not be able to connect to the database. Check config/database.yml and ensure PostgreSQL is running (sudo systemctl status postgresql).

2. How to configure email sending from Redmine?

To send notifications from Redmine (e.g., about new tasks or comments), you need to configure SMTP settings. Edit the config/configuration.yml file (if it doesn't exist, copy configuration.yml.example):

# config/configuration.yml
default:
  email_delivery:
    delivery_method: :smtp
    smtp_settings:
      address: "smtp.your-email-provider.com" # For example, smtp.mail.ru, smtp.gmail.com
      port: 587 # Or 465 for SSL
      authentication: :plain
      domain: "your_domain.com" # Your domain
      user_name: "noreply@your_domain.com" # Your email
      password: "your_email_password" # Email password
      enable_starttls_auto: true

After saving the file, restart the Redmine service (Puma): sudo systemctl restart redmine.service. Check sending a test email in Redmine settings (Administration -> Settings -> Email notifications).

3. What is the minimum VPS configuration suitable for Redmine?

For Redmine and a small team (up to 10 users), a VPS with 2 CPU cores, 4 GB of RAM, and 80 GB of SSD storage is minimally recommended. This will ensure sufficiently comfortable operation without noticeable delays. For larger teams or intensive use, consider 4 CPU cores and 8 GB of RAM.

4. What to choose — VPS or dedicated for this task?

For most Redmine use cases (small and medium teams, up to 50 active users), a VPS will be an optimal and cost-effective solution. A dedicated server should be chosen if you have a very large team, extremely high load, strict requirements for performance and resource isolation, or if you plan to host many other resource-intensive services on the same physical hardware.

5. How to update Redmine to a new version?

The Redmine update process involves several steps:

1. Backup: Perform a full backup of the database and the files directory.
2. Stop Redmine: sudo systemctl stop redmine.service.
3. Download new version: Download the new Redmine archive, unpack it into a new directory.
4. Copy files: Copy your config/database.yml, config/configuration.yml, config/initializers/secret_token.rb, as well as the files and plugins directories from the old installation to the new one.
5. Install gems: Navigate to the new Redmine directory and run bundle install --without development test.
6. Database migration: bundle exec rake db:migrate RAILS_ENV=production.
7. Start Redmine: sudo systemctl start redmine.service.

Always read the official update instructions for your specific Redmine version, as there may be specific steps.

6. Why are images/files not displayed or errors occur during upload?

This problem is most often related to incorrect permissions for the files directory or the absence of ImageMagick. Check the following:

• Permissions: Ensure that the /var/www/redmine/files directory and all its contents are writable by the user running Puma (redmineuser) and Nginx (www-data). Run: sudo chown -R redmineuser:redmineuser /var/www/redmine/files and sudo chmod -R 755 /var/www/redmine/files.
• ImageMagick: Redmine uses ImageMagick to process images (e.g., for previews). Make sure it is installed: sudo apt install imagemagick libmagickwand-dev -y.
• File size: Check client_max_body_size in your Nginx configuration. If you try to upload a file larger than allowed, Nginx may reject the request.

7. How to change the port Puma runs on?

By default, Puma listens on port 3000. To change it, edit the /var/www/redmine/config/puma.rb file and change the line port ENV['PORT'] || 3000 to your desired port, for example: port 3001. Then restart the Redmine service: sudo systemctl restart redmine.service. Don't forget to update your Nginx configuration if you are using a TCP port instead of a socket.

Conclusion and Next Steps

Congratulations! You have successfully installed and configured Redmine on your VPS, creating a reliable and fully controlled platform for project management and task tracking. Now your team can effectively collaborate, track progress, and achieve goals, with full control over their data and tools.

To maximize the potential of your new system, consider the following steps:

• Integration with Version Control Systems: Configure Redmine integration with your Git or SVN repositories to automatically link commits to tasks and view changes directly from Redmine.
• Plugin Installation: Explore the extensive library of Redmine plugins to extend functionality, such as additional reports, charts, integrations with other services, or user interface improvements.
• Performance Monitoring: Implement monitoring tools (e.g., Prometheus + Grafana) to track server load, memory and disk usage, and Redmine's own performance, to promptly react to potential issues.