Installation

Step-by-step guide to installing Redmine on your server.

This guide walks you through a fresh Redmine installation. Before you begin, review the System Requirements to ensure your server meets the prerequisites.

1. Extract the archive

   Download the Redmine release archive and extract it to your desired install path:

   tar -xzf redmine-x.x.x.tar.gz
   cd redmine-x.x.x
   
2. Create the database

   Create an empty UTF-8 encoded database for Redmine. The examples below use redmine as the database name.

   MySQL

   CREATE DATABASE redmine CHARACTER SET utf8mb4;
   CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
   FLUSH PRIVILEGES;
   

   PostgreSQL

   CREATE USER redmine WITH PASSWORD 'your_password';
   CREATE DATABASE redmine OWNER redmine ENCODING 'UTF8';
   

   SQLite3

   No setup required. SQLite3 creates the database file automatically during migration.

3. Configure database.yml

   Copy the example configuration and edit it for your environment:

   cp config/database.yml.example config/database.yml
   

   Edit config/database.yml and fill in your database credentials under the production block. See Database setup for full configuration examples.

   When using MySQL 8 or later, set transaction_isolation: "READ-COMMITTED" in the variables block. Redmine 5.1.1+ requires this to avoid concurrency issues.

4. Install required gems

   Install the gems needed for your environment:

   bundle install --without development test
   

   Bundler automatically installs only the database adapter gem matching the adapter value in config/database.yml. Re-run this command whenever you change the adapter.

   If ImageMagick is not installed on your server, skip the rmagick gem:

   bundle install --without development test rmagick
   

   To add gems not required by Redmine core (e.g. fcgi), create a Gemfile.local file in the application root. It is loaded automatically by bundle install.

5. Generate the secret token

   Redmine stores session data in cookies and requires a secret key:

   bundle exec rake generate_secret_token
   

   Do not share or commit the generated secret. Changing it invalidates all existing user sessions.

6. Run database migrations

   Create the database schema and the default administrator account:

   bundle exec rake db:migrate RAILS_ENV="production"
   
7. Compile assets (optional)

   By default, Redmine recompiles assets automatically when the application starts in production mode. To precompile them manually:

   bundle exec rake assets:precompile RAILS_ENV="production"
   

   When deploying to a sub-URI path, pass the relative URL root:

   bundle exec rake assets:precompile RAILS_ENV="production" RAILS_RELATIVE_URL_ROOT=/redmine
   

   If you encounter missing assets in the browser, clear the compiled output and recompile:

   bundle exec rake assets:clobber RAILS_ENV="production"
   bundle exec rake assets:precompile RAILS_ENV="production"
   
8. Set file permissions

   The user running Redmine must have write access to files, log, tmp, and public/assets. Assuming the system user is redmine:

   sudo chown -R redmine:redmine files log tmp public/assets
   sudo chmod -R 755 files log tmp public/assets
   

   Windows users can skip this step.

9. Start the server

   Start the Puma web server to verify the installation:

   ruby bin/rails server -e production
   

   Open http://localhost:3000/ in your browser. You should see the Redmine welcome page.

10. Log in and configure

    Use the default administrator credentials to log in:

    Field	Value
    Login	admin
    Password	admin

    Change the default password immediately after your first login.

    Navigate to Administration to load the default configuration data (roles, trackers, statuses, workflow) and adjust application settings.

Additional environment configuration

Copy config/additional_environment.rb.example to config/additional_environment.rb to override Rails environment settings such as log level, SSL enforcement, or custom Active Job adapters. Restart the application after editing this file.

SMTP configuration

Copy config/configuration.yml.example to config/configuration.yml and configure your SMTP settings. See Email configuration for details. Restart the application after any change to this file.