The Essentials
Install Command Line Tools
Installion of Command Line Tools for Mavericks has changed from the previous versions, there is now a single command you can run in the terminal to trigger the install.
xcode-select --install
You should see a pop-up window appear asking you to install, after clicking install just sit back and wait for it to finish.
Mountain Lion: If you're on Mountain Lion (or Lion) you will need to download Command Line Tools from Apple. The Apple Developer site requires you to sign in to access the downloads page but once you're in search for the Command Line Tools for your version, download and install.
What about Xcode?
You can install Xcode from the App Store but it's not essential. I find the FileMerge application comes in very useful but it's a large download just for that so be prepared to wait a little if you've not got a high-speed connection. Once it's downloaded, launch Xcode to make sure it's setup.
Install Homebrew
If you've not used Homebrew before you're going to love it. The self proclaimed missing package manager for OS X allows us to easily install the stuff we need that Apple doesn't include. Installation is simple, open Terminal (Applications » Utilities » Terminal) and copy this command:
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
# Add Homebrews binary path to the front of the $PATH
echo 'export PATH=/usr/local/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profileNow check our environment is correctly configured for Homebrew.
brew doctor
If there are any problems the brew doctor will give
you details about the it and sometimes even how to fix it. If not your probably not the only one so look it up in Google. Now we want to update Homebrew to make sure we're getting the latest formulas:
brew update
Install Ruby
OS X comes with Ruby installed (Mavericks even gets version 2.0.0, previously it was only 1.8.7), as we don't want to be messing with core files we're going to use the brilliant rbenv and ruby-build to manage and install our Ruby versions for our development environment.
Lets get brewing! We can install both of the required packages using Homebrew, once done we add a line to our ~/.bash_profile and
reload our terminal profile.
brew install rbenv ruby-build rbenv-gem-rehash
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
source ~/.bash_profileNow close terminal and open it again, this ensure everything has been reloaded in your shell.
The package we just installed allow us to install different versions of Ruby and specify which version to use on a per project basis and globally. This is very useful to keep a consistent development environment if you need to work in a particular Ruby version.
We're going to install the latest stable of Ruby (at the time of writing) you can find this out by visiting the Ruby website. Or to see a list of all available versions to install rbenv
install --list.
rbenv install 2.1.2
rbenv rehash
Let’s set this version as the one to use globally so we can make use of it in our terminal.
rbenv global 2.1.2
You can checkout more commands in the rbenv readme on Github. It's worth bookmarking that page for reference later, or there is always rbenv
--help.
Step 2 - Create an empty database and accompanying user
Redmine database user will be named redmine hereafter but it can be changed to anything else.
MySQL
CREATE DATABASE redmine CHARACTER SET utf8;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password';
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
For versions of MySQL prior to 5.0.2 - skip the 'create user' step and instead:
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost' IDENTIFIED BY 'my_password';
PostgreSQL
CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
SQL Server
The database, login and user can be created within SQL Server Management Studio with a few clicks.
If you prefer the command line option with SQLCMD, here's some basic example:
Step 3 - Database connection configuration
Copy config/database.yml.example to config/database.yml and edit this file in order to configure your database settings for "production" environment.
Example for a MySQL database using ruby 1.8 or jruby:
production:
adapter: mysql
database: redmine
host: localhost
username: redmine
password: my_password ＃不能加引號
Example for a MySQL database using ruby 1.9 (adapter must be set to mysql2):
production:
adapter: mysql2
database: redmine
host: localhost
username: redmine
password: my_password
If your server is not running on the standard port (3306), use this configuration instead:
production:
adapter: mysql
database: redmine
host: localhost
port: 3307
username: redmine
password: my_password
Example for a PostgreSQL database (default port):
production:
adapter: postgresql
database: <your_database_name>
host: <postgres_host>
username: <postgres_user>
password: <postgres_user_password>
encoding: utf8
schema_search_path: <database_schema> (default - public)
Example for a SQL Server database (default host localhost, default port 1433):
production:
adapter: sqlserver
database: redmine
username: redmine # should match the database user name
password: redminepassword # should match the login password
Install Bundler
Bundler manages an application's dependencies, kind of like a shopping list of other libraries the application needs to work. If you're just starting out with Ruby on Rails you will soon see just how important and helpful this gem is.
Step 4 - Dependencies installation
Redmine uses Bundler to manage gems dependencies.
You need to install Bundler first:
gem install bundlerThen you can install all the gems required by Redmine using the following command:
bundle install --without development testOptional dependencies
RMagick (allows the use of ImageMagick to manipulate images for PDF and PNG export)
If ImageMagick is not installed on your system, you should skip the installation of the rmagick gem using:
bundle install --without development test rmagickIf you have trouble installing rmagick on Windows, refer to this
HowTo.
Database adapters
Redmine automatically installs the adapter gems required by your database configuration by reading it from the config/database.yml file (eg. if you configured only a connection using
the mysql2 adapter, then only the mysql2 gem will be installed).
Don't forget to re-run bundle install --without development test ... after adding or removing adapters in the config/database.yml file!
Add the library path in your ~/.bash_profile or ~/.profile file:
MYSQL=/usr/local/mysql/bin
export PATH=$PATH:$MYSQL
export DYLD_LIBRARY_PATH=/usr/local/mysql/lib:$DYLD_LIBRARY_PATH
Step 5 - Session store secret generation
This step generates a random key used by Rails to encode cookies storing session data thus preventing their tampering.
Generating a new secret token invalidates all existing sessions after restart.
- with Redmine 1.4.x:
rake generate_session_store
- with Redmine 2.x:
rake generate_secret_token
Step 6 - Database schema objects creation
Create the database structure, by running the following command under the application root directory:
RAILS_ENV=production rake db:migrateWindows syntax:
set RAILS_ENV=production
rake db:migrateIt will create tables by running all migrations one by one then create the set of the permissions and the application administrator account, namedadmin.
Ubuntu troubleshooting:
If you get this error with Ubuntu:
Rake aborted! no such file to load -- net/https
Then you need to install libopenssl-ruby1.8 just like this: apt-get install libopenssl-ruby1.8.
Step 7 - Database default data set
Insert default configuration data in database, by running the following command:
RAILS_ENV=production rake redmine:load_default_dataRedmine will prompt you for the data set language that should be loaded; you can also define the REDMINE_LANG environment variable before running the command to a value which will be
automatically and silently picked up by the task.
E.g.:
Unices:
RAILS_ENV=production REDMINE_LANG=fr rake redmine:load_default_dataWindows:
set RAILS_ENV=production set REDMINE_LANG=fr rake redmine:load_default_data
Step 8 - File system permissions
NB: Windows users can skip this section.
The user account running the application must have write permission on the following subdirectories:
files(storage of attachments)log(application log fileproduction.log)tmpandtmp/pdf(create these ones if not present, used to generate PDF documents among other things)public/plugin_assets(assets of plugins)
E.g., assuming you run the application with a redmine user account:
mkdir -p tmp tmp/pdf public/plugin_assets sudo chown -R redmine:redmine files log tmp public/plugin_assets sudo chmod -R 755 files log tmp public/plugin_assets
Step 9 - Test the installation
Test the installation by running WEBrick web server:
- with Redmine 1.4.x:
ruby script/server webrick -e production
- with Redmine 2.x:
ruby script/rails server webrick -e production
Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.
Note: Webrick is not suitable for production use, please only use webrick for testing that the installation up to this point is functional. Use one of the many other guides in this wiki to setup redmine to use either Passenger (aka
mod_rails), FCGI or a Rack server (Unicorn, Thin, Puma, hellip;) to serve up your redmine.
Step 10 - Logging into the application
Use default administrator account to log in:
- login: admin
- password: admin
You can go to Administration menu and choose Settings to modify most of the application settings.
