Installation on Microsoft Windows

This procedure describes installation of Fat Free CRM 0.10.1-rc2 with MySQL storage on Microsoft Windows VMs and computers. I used stack installers to avoid many problems “new users” have setting up a Rails server. It works with Windows XP SP3, Vista SP2 and Windows 7. I tried to find the most straightforward way for my colleagues to try out Fat Free CRM on Windows and if you are trying to do the same, then this is for you.

Disclaimer

This procedure is provided without any express or implied warranty and using it is entirely at your own risk. Installing any software on a computer can have unintended consequences. You should back up your important files before trying this or any other installation.

Requirements

  • Fresh installation of Microsoft Windows XP SP3, Vista SP2 or 7 32-bit (physical or VM)
  • Single, working network connection with a fixed IP address
  • 512Mb RAM (XP VM), 768Mb (XP physical), 1Gb (Vista, 7 VM), 1.5Gb (Vista, 7 physical)
  • 2GB of NTFS formatted free disk space
  • User Account Control disabled on Vista and 7
  • Ability to use the Windows GUI and command prompt
  • Any 3rd party firewall configured correctly during installation

Caution!

If you intend to deploy Fat Free CRM in a production environment there is more work involved to achieve an acceptable level of performance and security. The versions of software I used may not be the most recent and may have security issues that you should review. Installing the operating system, server stack, application and data on the same physical disk will not provide sufficient performance in production use. You should consider running the software and stack under separate and limited user accounts to restrict file system and database access in the event of intrusion.

Software to download before you begin

If you do not have a notepad app that can recognize different character sets (Windows Notepad is not really up to the task) then I suggest installing Metapad 3.6 from http://liquidninja.com/metapad/download.html

Install XAMPP

  1. Double-click xampp-win32-1.7.4-VC6-installer.exe
  2. Wait for installer to verify, choose language, and default installation folder
  3. On XAMPP Options screen, tick Install MySQL as service, then click Install, wait, click Finish
  4. Wait for installation finished message, click OK, click No to the control panel question
  5. Restart the VM/Computer
  6. Double-click XAMPP Control Panel icon on desktop, check that MySql has “running” beside it
  7. Click Start beside Apache, if Windows Firewall is enabled and gives a warning, click Unblock
  8. Open your browser and go to http://127.0.0.1, choose language
  9. Click Security in left column, scroll down page that opens, click xamppsecurity.php link
  10. Enter a MySQL root password and click Password changing then write it down
  11. Go back to the XAMPP control panel (on taskbar or icon in the tray area)
  12. Beside MySql, click Stop, count to 5, then click Start
  13. Go to http://127.0.0.1/phpmyadmin and login with username root and password from step 10.
  14. If login is successful, MySQL is running and you can click the green exit icon (top left corner of page)
  15. Close browser and all windows and restart the VM/Computer

Run Rails Installer

  1. Double-click railsinstaller-1.2.0.exe then click Next to step through
  2. Accept license, default folder, click Install, wait, then click Finish
  3. Enter a name and email (user@host.org is ok). When the command completes, close the window.

Install rubygems, rake and other libs

  1. Unzip rubygems-1.8.5.zip and copy the folder from the zip to C:\RailsInstaller. The structure should then be C:\RailsInstaller\rubygems-1.8.5 with subfolders bin, test, util, etc.
  2. Go to RailsInstaller on the Start menu, and click Command Prompt with Ruby and Rails
  3. Run the following commands:
    
    cd C:\railsinstaller\rubygems-1.8.5`
    ruby setup.rb
    gem install --no-rdoc --no-ri rake -v 0.8.7
    gem install --no-rdoc --no-ri rails3-generators
    
  4. When commands are complete, close the Command Prompt window

Install mysql2 lib and libmysql.dll

  1. Unzip mysql-5.5.8-win32.zip go into the mysql-5.5.8-win32 folder and copy the subfolder include to C:\xampp\mysql The structure should then be C:\xampp\mysql\include, containing a large nuber of .h files
  2. Run the following commands:
    
    cd C:\railsinstaller\
    subst X: C:\xampp\mysql
    gem install --no-rdoc --no-ri mysql2 -v 0.2.7 -- with-mysql-dir=X: --with-mysql-lib=X:\bin --with-mysql-include=X:\include
    gem update bundler
    
  3. When commands are complete, close the Command Prompt window
  4. Using Windows Explorer, go to C:\xampp\mysql\bin and copy libmysql.dll to C:\RailsInstaller\Ruby1.8.7\bin

Install the Fat Free CRM application

  1. Unzip the Fat Free CRM zip file (e.g. fatfreecrm-fat_free_crm-0.10.1-rc2-0-g37bc96e.zip), and copy the folder fatfreecrm-fat_free_crm-37bc96e to C:\RailsInstaller, then right click and rename the folder to fat_free_crm
  2. The folder structure should then be C:\RailsInstaller\fat_free_crm

Edit configuration files

  1. At this point you will need to edit 3 different text files with a UNIX compatible editor. Windows notepad is NOT suitable. If you do not have a different editor please scroll up to Software to download before you begin and download Metapad from the link, then unzip and run it. The files can be dragged and dropped straight in to Metapad.

  2. In Windows Explorer, go to C:\railsinstaller\ffcrm\config and open database.mysql.yml in your editor.

  3. Scroll down to the production: section

  4. Beside password:, type the MySQL password you wrote down before. (Leave a space after the colon.)

  5. Add a line under socket: /tmp/mysql.sock that says host: 127.0.0.1.

  6. The file should look something like this:

       production:
         adapter: mysql2
         encoding: utf8
         database: crm_production
         pool: 5
         username: root
         password: -your-pass-here-
         socket: /tmp/mysql.sock
         host: 127.0.0.1
    

  7. Save the file as a new file at C:\railsinstaller\ffcrm\config\database.yml.

  8. Go to C:\railsinstaller\ffcrm\config\environments and open production.rb in your editor, scroll down and paste in the following code block just above end:


config.action_mailer.perform_deliveries = true

config.action_mailer.delivery_method = :smtp

ActionMailer::Base.smtp_settings = {
  :address => "smtp.gmail.com",
  :enable_starttls_auto => true,
  :port => 587,
  :authentication => :plain,
  :user_name => "user@domain.com",
  :password => 'password'
}

config.action_mailer.default_url_options = { :host => 'dev.mydomain.com' }

Then double check to make sure end is still the last line of the file and save the file.

Configure the application and create a blank database

  1. Go to RailsInstaller on the Start menu and click Command Prompt with Ruby and Rails
  2. Run the following commands:
    
    cd C:\railsinstaller\ffcrm
    bundle install  # (this command takes about 5 minutes to complete)
    rake db:create RAILS_ENV=production
    rake ffcrm:setup RAILS_ENV=production
    
  3. Enter the administrator username and password you want when asked, then type yes (and press enter) to continue.

Run Fat Free CRM

  1. In the Command Prompt, type:
    
    rails server -e production
    
  2. Wait for the server to start (can take 30 seconds). A timed server log will appear when it’s ready
  3. The application is now available on the local machine at http://127.0.0.1:3000

Open firewall for network access

  1. The server listens on port 3000 so this must be opened at the firewall to allow access from the network
  2. On Windows Vista or 7 go to the Control Panel, then the Network and Sharing Center, then click Windows Firewall (bottom left) then Change settings (on the right). Go to step 9.4
  3. On Windows XP go to the Control Panel, then Network and Internet Connections, then click Windows Firewall at the bottom
  4. When the Windows Firewall Settings dialog box appears, click the Exceptions tab, then click Add port and use the following:

    Name:Rails
    Port number:3000
    Click OK to the dialogs.
  5. You can then type http://192.168.1.1:3000 (replace 192.168.1.1 with your own IP address) to access Fat Free CRM from any computer on your local subnet

Developed by the Pinstripes Windows Server Lab, July 2011

Sources