Redmine 1-Click Documentation

1. How the installer works

The installer is a single self-contained Bash script. It runs sequentially through a fixed set of steps, displaying a progress bar for each one. The total number of steps is 18 for a standard installation, or 19 if SSL is enabled (Let's Encrypt or manual certificate).

The steps are organised into the following phases:

1. 1
   Preflight checks Verifies root privileges, OS compatibility, required config values, and detects a previous partial run to resume from.
2. 2
   System update & dependencies Runs apt-get update, apt-get upgrade, and installs the system packages and libraries needed to install Ruby and run Redmine.
3. 3
   Swap setup If total swap is below 1 GB, a 2 GB swap file is created automatically. This protects low-RAM VPS instances when Ruby needs to be compiled as a fallback and is not counted as an installation step.
4. 4
   Database installation & configuration Installs the chosen database server (MariaDB or PostgreSQL), enables the service, and creates the Redmine database and user.
5. 5
   Ruby installation (package-first) Attempts to install the required Ruby version from OS packages first (fast path). If that exact version is not available as a package, it falls back to rbenv/ruby-build in /usr/local/rbenv and compiles Ruby. Bundler is installed afterward.
6. 6
   Redmine installation Downloads the Redmine source archive, extracts it, writes database.yml, runs bundle install, generates the secret token, runs database migrations, loads default data, and sets the admin account credentials.
7. 7
   Web server installation & configuration Installs Apache or Nginx with Passenger, writes the virtual host configuration, and enables the site.
8. 8
   SSL certificate Only present if SSL mode is Let's Encrypt or manual. Runs Certbot or configures the provided certificate files.
9. 9
   Log rotation & summary Writes a logrotate rule for Redmine logs, then prints a summary with the access URL, credentials, and useful paths.

What it looks like

These screenshots show a real installation on Ubuntu 22.04 with MariaDB and Nginx. The installer displays a progress bar with step count, percentage, and elapsed time for each phase.

Click to enlarge

Click to enlarge

2. Slow steps, interruptions & resume

Steps that take the longest

While a step is running, the terminal shows a spinning indicator and an elapsed timer. The installer is working even if it appears frozen — do not close the terminal or press Ctrl+C. Two steps are significantly slower than the rest:

Resuming after an interruption

After each successful step, the installer saves its progress to a state file:

If the script is interrupted (network loss, SSH disconnect, power cut, Ctrl+C) or fails at a specific step, simply re-run the same script with sudo. It will detect the state file and skip all already-completed steps, resuming from where it stopped.

The state file is deleted automatically when the installation completes successfully.

3. Error handling — abort vs. continue

Not all problems are treated equally. Some conditions stop the installation immediately; others produce a warning and allow the script to continue.

Conditions that abort the installation

The script exits immediately and displays an error message.

When a step fails, the installer prints the last 30 lines of the step's output to the console and writes the full output to the log file. The state file is preserved so the installation can be resumed after the problem is fixed.

Conditions that generate a warning and continue

4. The installation log

All installer activity is written to a persistent log file:

What is captured:

• Every progress message, warning, and error printed to the console.
• The full stdout and stderr of each installation step — including apt output, gem installation details, compilation logs, rake output, etc.
• On step failure: the last 30 lines of the failed step's output (also shown on screen).
• The final installation summary with URLs, credentials, and paths.

The log file is never deleted or truncated by the installer. Subsequent runs append to it, so it accumulates history across resume attempts.

To follow the log in real time during installation:

5. Credentials & sensitive data

Passwords are not kept in our database or transaction records. They exist on our server only temporarily during the checkout process and inside the generated script file during the 48-hour download window, then are permanently deleted. Configuration data (domain, database name, admin username, etc.) is also kept temporarily for up to 48 hours and then permanently deleted. Credentials and server commands are shown once and cannot be recovered later. Save them in a secure place before closing the page.

During installation, credentials are also written on the target server to:

This file is created with root-only permissions and is intended as your local recovery copy.

What to share with support

Share the sanitized support log only:

Do not share /root/redmine-credentials.txt or any raw credentials unless you have rotated them first.

6. Email notifications

The installer does not configure outgoing email. SMTP credentials (server address, username, password) are sensitive authentication data, and we deliberately avoid collecting or transmitting them through our infrastructure.

After installation, Redmine works normally without email — notifications are simply not sent until you add your SMTP settings to the configuration file on your server:

For a complete walkthrough — including example SMTP settings for Gmail, Microsoft 365, Amazon SES, and other providers — see the dedicated guide:

Email Notifications Setup Guide →

7. How to install plugins

Plugins can add application code, gem dependencies, and database migrations. Confirm compatibility with your exact Redmine and Ruby versions, follow the plugin author’s installation notes, and back up your database and attachments before changing production.

1. Copy the plugin into Redmine

Each plugin belongs in its own directory under /opt/redmine/plugins/. Clone it as the redmine user; replace the repository URL and directory name with the values from the plugin author:

If you upload and extract an archive as another user, make sure the plugin directory contains its init.rb file and set ownership:

2. Install any required gems

R1C configures Bundler once during installation to store gems in /opt/redmine/vendor/bundle. You do not need to repeat that configuration for each plugin. After adding a plugin that requires gems, run:

Always run Bundler as redmine, not as root.

3. Run plugin migrations, if required

Only run this step if the plugin includes database migrations:

4. Precompile assets, if required

If the plugin includes stylesheets, JavaScript, or other frontend assets, precompile them after installing its gems and running any required migrations:

5. Restart Passenger

Restart the Redmine application service for your R1C web server:

• Nginx + Passenger: sudo systemctl restart redmine-passenger
• Apache + Passenger on Debian or Ubuntu: sudo systemctl restart apache2

Sign in and verify the plugin. If Redmine does not start, inspect /opt/redmine/log/production.log and the web server error log. Follow any additional steps documented by the plugin author.

8. How to install a custom theme

A custom theme changes Redmine’s appearance without adding a plugin. Confirm that the theme supports your Redmine version and download it from a trusted source.

1. Choose the themes folder

2. Install the theme files

The theme must have its own directory directly inside the themes folder. To clone a Git-hosted theme, run the command for your Redmine version and replace the repository URL and theme name:

Redmine 6 and later

Redmine 5 and earlier

If you upload and extract a theme archive as another user, set ownership after extraction:

Redmine 6 and later

Redmine 5 and earlier

3. Precompile assets

For Redmine 6 and later, precompile assets after installing the theme files so Redmine can serve the theme’s stylesheets and JavaScript in production:

4. Select the theme in Redmine

Restart the application service shown in your R1C installation summary. Nginx + Passenger uses redmine-passenger; Apache + Passenger on Debian or Ubuntu uses apache2. Sign in as an administrator and go to Administration → Settings → Display, select the theme, and save. Refresh the page; clear your browser cache if the old styles remain.

Theme-only installs do not require bundle install or plugin migrations unless the theme author documents additional requirements.