Some Notes Before We Start
When you have a webserver running you probably would like redmine through that server aswell to keep things easier, reducing port forwarding requirements and the number of addresses you hand out. You could just hand out the new address which usually looks like http://localhost:3000/ if you want, but why not do a proper integration.
These methods will allow you to run redmine from your normal webserver or localhost, http://localhost/ with no port number on the end (this assumes that your webserver does not have a port number, using port 80).
Tthere are 2 parts of this process to consider:
- Changing the folder from which redmine is server ie from http://localhost:3000/ to http://localhost:3000/redmine/
- Proxying / Redirecting redmine from the server where it is (ie http://localhost:3000/) to youer apache server http://localhost/
With the following instructions i will assume the following
- Redmine is located at http://localhost:3000/
- The target apache server http://localhost/redmine/ - might need to amend this rule
NB if you are just running your apache at http://localhost/ you can just use the following instead http://localhost/redmine/
If you just want the code, click here, this will take you to the bottom where you can just get the code for a quick start without any of the history.
Files
This section is not required reading but might help if you have issues or question later on.
During my research i cam across references to Redmine files where you could put code. I am going to list them here and what i think they do.
- {redmine}/config.ru - this is the intialization configuration file, i think
- {redmine}/config/enviroment.rb - This file controls additonal settings that will get applied to both development and production enviroments
- {redmine}/config/additional_enviroment.rb - This is only present in later version of Ruby/Rails/Redmine and probably needs creating. . This file controls additonal settings that will get applied to both development and production enviroments similiar enviroment.rb does. Not all commands in this file work in this file that would in enviroment.rb .
- {redmine}/config/application.rb - dont bother altering code in this
- {redmine}/config/development.rb - this files allows you to add additional commands/instructions to just the development enviroment
- {redmine}/config/production.rb - this files allows you to add additional commands/instructions to just the production enviroment
Move Redmine to a Sub-Folder
Method 1 - Using WebBrick
This techniques is the best an i have taken most of the information from Defect #12102: Installed Redmine in a sub-URI: Links are generated not correctly - Redmine
This method also utilises the inbuilt WebBrick Webserver, This is an excellent simple solution but if you are going to use this for a lot of users you should perhaps think about using Thin Server, this will require slightly different instructions and some more work. WebBrick is classed as a reference server and if you are going to server more than 20 people at a time there will be large performance issues. For the most of us WebBrick will be fine.
config.ru
# This file is used by Rack-based servers to start the application. require ::File.expand_path('../config/environment', __FILE__) map '/redmine' do run RedmineApp::Application end
Replace the contents of {redmine}/config.ru with this code. This also assumes you have not already made any alterations to this file.
This code does 2 things
- changes all links in the pages to /redmine/
- changes the actual served root. Files in the /public/ directory are now served as http://3000/redmine/ instead of http://localhost:3000/
The root folder effectively no longer exists, you get page not found supplied by the webserver if you browse to http://localhost:3000/ and this is normal.
Other Static Asset Commands
You can also change the dynamic urls by using the 2 following commands:
- RedmineApp::Application.routes.default_scope = { :path => '/redmine', :shallow_path => '/redmine'
- RedmineApp::Application.routes.default_scope = '/redmine'
which cause the following issues:
- the directory of the dynamic links changes but the root of the webserver stays the same. This means that the static files stay in the root directory (http://localhost/) while all of the dynamic links are in http://localhost:3000/redmine/
- it is very difficult to proxy these 2 folders because this will involve complex rewrite rules
enviroment.rb
ActionController::Base.relative_url_root = '/redmine'
Add this to the end of {redmine}config/enviroment.rb. I also think you can put this in either development.rb or production.rb, this change will then only occur in that particular enviroment.
This code alters the path of the links pointing to the static files such as javascripts and CSS. Currently all paths for these still point to the root http://localhost:3000/ but they actual ar now present at http://localhost:3000/redmine/ and even though we have added the code in config.ru these paths are not altered so we need this code to correct that.
NB:
- RedmineApp::Application.routes.default_scope = '/redmine' works but is not the prefered method. This must also be put before RedmineApp::Application.initialize!
- ActionController::AbstractRequest.relative_url_root = "/redmine" - Does not work, it was for older versions of Redmine
- config.action_controller.relative_url_root = '/redmine' - not sure about this
You now have moved your Redmine installation to a subfolder
Method 2 - Thin Server + Passenger Server
this will be for my Thin server notes when i do them, there is also the Passenger Webserver to consider. Each has there own method. Basically youo can run these servers with switches to perform the directory change, You can then proxy this over to your main webserver as in the instructions below. Check my General Links section for resources.
Proxying Redmine to Apache / Xampp
Redmine in Root Folder
This is the easiest of the methods to implement. You can simply proxy Remine to your apache server using the following code, this assumes redmine is at http://localhost:3000/
httpd.conf
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Make sure these modules are enabled in httpd.conf, they are required.
ProxyRequests Off ProxyPreserveHost On ProxyPass / http://localhost:3000/ ProxyPassReverse / http://localhost:3000/
Add these lines to the end your apache httpd.conf , if you do this you will not be able to run any other stuff from your apache webserver because all requests will get forwarded to the Redmine server.
Or Alter the Redmine Server port directely
Simply run the Redmine server on port 80 by using the following switch which will give the same effect
-p 80
Redmine in Subfolder
Method 1 - Basic (also blunt and site wide)
These instructions will assume the subfolder on apache you want is http://localhost/redmine/
.htaccess file
# Redirects /redmine to /redmine/ RedirectMatch ^/redmine$ /redmine/ RedirectMatch ^/$ /redmine/
add this code to ..../htdocs/.htaccess in your apache server.
You can redirect the non-slashed version, but this is to make sure we have a correct URL. A directory is denoted by having a slash at the end of the URL (ie /redmine/ ) wheresas if you dont, it denotes a page (ie /redmine ).
What we are directing to is more akin to a directory/default index file like a normal webserver, http://www.example.com/ You dont often see http://www.example.com/index.html , but they are the same page. Notice the slash at the end, this is intentional.
httpd.conf
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Make sure these modules are enabled in httpd.conf, they are required.
ProxyRequests Off ProxyPreserveHost On ProxyPass /redmine/ http://localhost:3000/redmine/ ProxyPassReverse /redmine/ http://localhost:3000/redmine/
This is code that actualy passes the information/request between Redmine Server and your Apache server.
- ProxyRequest - This function provides forward proxying services and is not required here. This will prevent abuse of your server.
php - Apache ProxyRequest - Server Fault - not required for reverse proxies, this must be off
ProxyRequests Off - not working and httpd being abused as forward proxy | Apache | Users - turns of forward proxy requests - ProxyPreserveHost - keeps header information in the request sent to the Redmine Server so things work nicely. If you want more information about this use google.
- ProxyPass and ProxyPassReverse - these handle the proxy mappings.
Can I make this Better
The commands above will work site wide so are a bit blunt, the following methods will allow you to apply these rules to a specific locations.
Method 2 - <Location>
<Location> works on the URLs presented to the server
httpd.conf
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Make sure these modules are enabled in httpd.conf, they are required.
ProxyRequests Off <Location /redmine/> RedirectMatch ^/redmine$ /redmine/ RedirectMatch ^/$ /redmine/ ProxyPreserveHost On ProxyPass http://localhost:3000/redmine/ ProxyPassReverse http://localhost:3000/redmine/ </Location>
- ProxyRequests Off will not work in <Location>
- Notice that the proxy statements do not have a target in them, only the source
- The RedirectMatch commands will work outside of <Location>
- rules in <location> can be moved easier that <directory> because there are not absolut addresses
With this method you have to split the commands, ProxyRequests will not work in location so needs to be put in the normal flow of the httpd.conf (i.e. not in <location>)
Method 3 - <Directory>
Directory works on the physical path of the accessed files and is better to be used for security because several URLs can point to a single directory or file whereas the <Directory> command is very specific.
httpd.conf
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Make sure these modules are enabled in httpd.conf, they are required.
ProxyRequests Off <Directory "d:\Documents\Developer\xampp\htdocs\redmine\"> RedirectMatch ^/redmine$ /redmine/ RedirectMatch ^/$ /redmine/ ProxyPreserveHost On ProxyPass http://localhost:3000/redmine/ ProxyPassReverse http://localhost:3000/redmine/ </Directory>
- ProxyRequests Off will not work in <Location>
- Notice that the proxy statements do not have a target in them, only the source
- <Directory "D:/Documents/Developer/xampp/htdocs/redmine/"> is also valid
- this command acts on the Virtual Directory in the xampp public folder
- This should work even though the directory does not exist
- The RedirectMatch commands will work outside of <Directory>
Method 4 - VirtualHost
With Virtualhost you can run a another domain name on the 1 xampp/apache server. This is very useful. You can also just use it to apply rules to the server and keep the code neater, easier for copying and pasting.
httpd.conf
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Make sure these modules are enabled in httpd.conf, they are required.
<VirtualHost *:80> ## This is for setting a domain name ServerName rails.localhost.com DocumentRoot "D:\Documents\Developer\RubyRoot\redmine\public\" # Make sure there is a trailing slash in the root RedirectMatch ^/redmine$ /redmine/ RedirectMatch ^/$ /redmine/ # The proxying code ProxyRequests Off ProxyPreserveHost On ProxyPass /redmine/ http://localhost:3000/redmine/ ProxyPassReverse /redmine/ http://localhost:3000/redmine/ </VirtualHost>
- If you want to run another domain on you local webserver you need to add a rule to your Hosts file, ie 127.0.0.1 rails.localhost.com
- All the code required is contained within <VirtualHost> tags
- This code be used on the whole server or just an individual domain (depends if you define ServerName)
Including the rules in the <VirtualHost> tags is not required but can make handling the code easier and if you do want apply this to a specific domain it is easy to enable it.
My Code
So you have arrived here at the code, just following the simple instructions and edit the files. Redmine will then run at http://localhost/redmine/ on you xampp installation. This does of course assume you have Redmine already running on your Windows PC.
Redmine - config.ru
# This file is used by Rack-based servers to start the application. require ::File.expand_path('../config/environment', __FILE__) map '/redmine' do run RedmineApp::Application end
Replace the contents of {redmine}/config.ru with this code. This also assumes you have not already made any alterations to this file.
Redmine - enviroment.rb
ActionController::Base.relative_url_root = '/redmine'
Add this to the end of {redmine}config/enviroment.rb. I also think you can put this in either development.rb or production.rb, this change will then only occur in that particular enviroment.
Apache / Xampp - httpd.conf
Edit your Apache / Xampp httpd.conf file
LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so
Make sure these modules are enabled in httpd.conf file, they are required.
################################# # RUBY SETUP ################################# # Enforces a trailing slash for the /redmine/ directory RedirectMatch ^/redmine$ /redmine/ RedirectMatch ^/$ /redmine/ # The proxying code ProxyRequests Off ProxyPreserveHost On ProxyPass /redmine/ http://localhost:3000/redmine/ ProxyPassReverse /redmine/ http://localhost:3000/redmine/ ################################# # RUBY SETUP #################################
Add these lines at the bottom of the httpd.conf file.
Done
All the changes are now done, you will find that Redmine will be served from http://localhost/redmine/ and http://localhost:3000/redmine/ , this is normal.
If you had your servers running while making these changes you need to restart them both.
You should note that this setup is non-SSL version so is not secure.
General Links
These are the links i used for my research and might be of use.
Redmine / Ruby
- HowTo Install Redmine on subdirectory (sub-URI) on Apache - Redmine
- Defect #11881: FCGI mode does not support sub-URI - Redmine
- Defect #12102: Installed Redmine in a sub-URI: Links are generated not correctly - Redmine - This is where i got the proper subdirectory code that works and also has the code for SSL usage
- Subdirectory problem with Redmine 2.1.2 under Windows - Redmine - Run Redmine in a subfolder using the Thin Server
- HowTo Install Redmine in a sub-URI - Redmine - The official page to get Redmine in a sub-URI / Sub-directory. It is dated and uses the mongrel server to work
- HowTo Install Redmine in a sub-URI on Windows with Apache - Redmine - Again this uses Mongrel and the instructions are probably out of date
- HowTo have both development and production environment available from Apache with VirtualHost - Redmine
- Apache2 + passenger configuration - Redmine
- Redmine not working properly from a subdirectory - Redmine - An unsuccessful attempt to run Redmine in a sub directory but they did get some things right
- Thin - yet another web server - Homepage of the Thin Server
- How do I configure Apache 2.2 for Ruby on Rails in Windows? - Stack Overflow
- apache 2.2 - How to configure Apache2 for Redmine properly? - Server Fault - Useful setup info for redmine suing apssenger on Debian Linux
- apache 2.2 - Virtualhost setup for Ruby on Rails application (mod passenger) - Server Fault
- Apache configuration for installing Redmine in URL subdirectory - Stack Overflow - mentions Phusion Passenger and the appropriate configuration
- Changing the base URL for Rails 3 development - Stack Overflow - This also has the correct subfolder fix for Redmine
Reverse Proxy
- Running a Reverse Proxy with Apache
- Using mod_rewrite for Proxying - Apache HTTP Server Version 2.2
- Using mod_rewrite for Proxying - Apache HTTP Server Version 2.4
- mod_proxy_html - Apache HTTP Server Version 2.4
- Running a Reverse Proxy in Apache
- mod_proxy - Apache HTTP Server Version 2.2
- How to set up a proxy server with XAMPP on Windows
- Use mod_rewrite’s proxy flag with caution — statichtml.com
- reverse proxy - Setting Redmine path - Server Fault - uses ProxyHTMLMap command, not sure if this alters hyperkinks in the content
- apache - ProxyPreserveHost seems to do little for me - Stack Overflow explains a little about ProxyPreserveHost in simple terms
- apache - Can ProxyPass and ProxyPassReverse work in htaccess? - Stack Overflow - No you cant, and this tells you why
- xampp - How can I enable mod_proxy_http - Server Fault - mentions security when using Proxy
- Apache config and .htaccess - URL rewriting - Reverse Proxy
- Configuring Ruby On Rails App in a subdirectory under Apache - Stack Overflow
- mod rewrite - Apache rewriterule with proxyPass and proxyPassReverse - Stack Overflow
Apache
- VirtualHost Examples - Apache HTTP Server Version 2.2
- Difference between and Apache directives - Server Fault
- <Directory> Directive - Official Documentation
- <VirtualHost> Directive - Official Documentation
- <Location> Directive - Official Documentation
- Rewriting URLs in hyperlinks (Configure Apache as a reverse proxy) - This article discuss rewriting hyperlinks in the source before serving the code and how this can take a lot of processing
- Apache's features to manipulate URL's
- mod rewrite - Apache mod_rewrite internally to different port - Stack Overflow
- apache 2.2 - How to configure Apache2 for Redmine properly? - Server Fault - this mentions Passenger and RailsBaseURI