BitNami RubyStack Stack 2.0-2 ============================= 1. OVERVIEW The BitNami Project was created to help spread the adoption of freely available, high quality, open source web applications. BitNami aims to make it easier than ever to discover, download and install open source software such as document and content management systems, wikis and blogging software. You can learn more about BitNami at http://bitnami.org Ruby is a dynamic, open source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write. You can learn more about Ruby at http://www.ruby-lang.org Ruby on Rails is a full-stack MVC framework for database-backed web applications that is optimized for programmer happiness and sustainable productivity. It lets you write beautiful code by favoring convention over configuration. You can learn more about Ruby at http://www.rubyonrails.org The BitNami RubyStack is an installer that greatly simplifies the installation of Ruby on Rails and its runtime dependencies. It includes ready-to-run versions of Ruby, Rails, MySQL and Subversion. RubyStack is distributed for free under the Apache 2.0 license. Please see the appendix for the specific licenses of all open source components included. You can learn more about BitNami Stacks at http://bitnami.org/stacks/ 2. FEATURES - Easy to Install BitNami Stacks are built with one goal in mind: to make it as easy as possible to install open source software. Our installers completely automate the process of installing and configuring all of the software included in each Stack, so you can have everything up and running in just a few clicks. - Independent BitNami Stacks are completely self-contained, and therefore do not interfere with any software already installed on your system. For example, you can upgrade your system's MySQL or Apache without fear of 'breaking' your BitNami Stack. - Integrated By the time you click the 'finish' button on the installer, the whole stack will be integrated, configured and ready to go. - Relocatable BitNami Stacks can be installed in any directory. This allows you to have multiple instances of the same stack, without them interfering with each other. 3. COMPONENTS BitNami RubyStack ships with the following: - Ruby 1.8.7-2009.10 - RubyGems 1.3.5 - Rails 2.3.5 - ImageMagick 6.5.8 - Subversion 1.6.6 - SQLite 3.5.1 - MySQL 5.1.30 - Apache 2.2.13 - PHP 5.2.11 - phpMyAdmin 2.11.9.4 - Git 1.6.5.2 - Nginx 0.7.64 - Sphinx 0.9.8.1 4. REQUIREMENTS To install BitNami RubyStack you will need: - Intel x86 or compatible processor - Minimum of 512 MB RAM - Minimum of 150 MB hard drive space - TCP/IP protocol support - Compatible operantig systems: - An x86 Linux operating system. - A 32-bit Windows operating system such as Windows 2000, XP, Vista or Windows Server 2003. - An OS X operating system (PowerPC or x86). 5. INSTALLATION The BitNami RubyStack is distributed as a binary executable installer. It can be downloaded from: http://www.bitnami.org/stacks/ The downloaded file will be named something similar to: bitnami-rubystack-2.0-2-windows-installer.exe on Windows or bitnami-rubystack-2.0-2-linux-installer.bin on Linux or bitnami-rubystack-2.0-2-osx-x86-installer.bin on OS X x86 or bitnami-rubystack-2.0-2-osx-powerpc-installer.bin on OS X PowerPC. Double click the file and follow the on-screen instructions. If you receive an error message during installation, please refer to the Troubleshooting section. 5.1 MODULES On top of the RubyStack you can run a series of applications that come as modules or plugins. These so called modules allow you to reuse your RubyStack installation to run different applications at the same time, without having to redownload all the RubyStack dependencies again. This results in installers between 2 and 20MB, which allows you to download and tryout your favourite application quickly. A list of modules is available at http://www.bitnami.org/stacks 5.1.1 MODULES INSTALLATION A BitNami module should have the word "module" in it's filename. If this is not the case, then you probably downloaded the full version of the application (including all it's dependencies), or the module version of the application is not available yet. We are continiously adding more modules, if you want to be notified when new modules are released, we advise you to sign up for our newsletter: To do so, just register at: http://www.bitnami.org/catalog/newsletter. Double click the file or launch it via the console and follow the on-screen instructions. Two parameters are specifically important during the installation: - RubyStack Location: Enter the path where your RubyStack is installed - MySQL Password: Enter the root password of your existing RubyStack installation After this you may be asked to specify a username and password for the application that you are installing. Once the installation is finished your application should appear on the following page: http://localhost:8080/applications.html Note that localhost and 8080 may vary, depending on your installation. It is important to note that the RubyStack installation that you have should be higher than version 1.3-beta1. Attempts with older versions will fail. 6. STARTING AND STOPPING BITNAMI RUBYSTACK You can start and stop BitNami RubyStack on Windows using the shortcuts created in the Start Menu, under Programs -> BitNami -> BitNami Service on Windows. To start/stop/restart application on Linux or OS X you can use the ctlscript.sh utility: ./ctlscript.sh (start|stop|restart) ./ctlscript.sh (start|stop|restart) mysql ./ctlscript.sh (start|stop|restart) apache ./ctlscript.sh (start|stop|restart) subversion start - start the service(s) stop - stop the service(s) restart - restart or start the service(s) 6.1. DEPLOY RUBY ON RAILS APPLICATION ON THE STACK. 6.1.1 Using Apache with Mongrel This approach consists on having multiple Mongrel processes running in different ports. Once they are running, Apache will be set up as a proxy balancer, sending the Rails requests to those ports. In order to set up the group of Mongrels, you may configure a mongrel cluster or generate a windows service for each of them. On Linux and OS X you can use mongrel_cluster plugin to start/restart/stop a group of mongrels easily. You can create a mongrel cluster configuration file running: mongrel_rails cluster::configure -e production -p 3001 -N 2 -C ${rails_application_dir}/config/mongrel_cluster.yml This will create a cluster with two mongrels starting at port 3001 storing the settings in mongrel_cluster.yml. Then, to start the cluster you can type: cd ${rails_application_dir} mongrel_rails cluster::start On Windows you can install the mongrels as Windows services: mongrel_rails service::install -N "service_name" -p "port" -c "application_directory" To start the service you can use Windows service tool or you can type:

net start "service_name" To uninstall the service: mongrel_rails service::remove -N "service_name" or sc delete "service_name" Regarding Apache, you may include the following lines to apache2/conf/httpd.conf: ProxyPass /appname balancer://appcluster ProxyPassReverse /appname balancer://appcluster BalancerMember http://127.0.0.1:3001/appname BalancerMember http://127.0.0.1:3002/appname ... That way, each time a Rails request is received it will be sent to the mongrels running in ports 3001, 3002... After restarting Apache the application should be accessible at http://domain:port/appname. 6.1.2 Using Apache with Passenger If you are using Linux or OS X, you can deploy the application with Phusion Passenger. In this case, Mongrel processes are not necessary. To apply this method we just need to include a virtual host which DocumentRoot points to 'public' directory in Rails application. ServerName myapplication.com DocumentRoot ${rails_app_dir}/public Allow from all Options -MultiViews You should make sure that 'public' and 'config' applicaton folders and their parent directories are readable and executable by Apache. You can find more information about Phusion Passenger settings at http://www.modrails.com/documentation.html 6.1.3 Using Nginx with Mongrel This approach consists on having multiple Mongrel processes running in different ports. Once they are running, Nginx will be set up as a proxy balancer, sending the Rails requests to those ports. In order to setup the set of Mongrels, you may configure a mongrel cluster or generate a windows service for each as it was described in previous section. Regarding Nginx, you may include a new file nginx/conf/vhosts/railsapp.conf with the contents: upstream backend {
server 127.0.0.1:3001;
server 127.0.0.1:3002;
... } server { location /appname { proxy_redirect off; port_in_redirect off; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; if (-f $request_filename) { break; } if (!-f $request_filename) { proxy_pass http://backend; break; } } } That way, each time a Rails request is received it will be sent to the mongrels running in ports 3001, 3002... Static files located in public dir will be served by nginx directly. Finally, we start nginx: /nginx/sbin/nginx (linux, osx) \nginx\nginx.exe (windows) By default, nginx server uses port 1234 but it can be changed adding a "listen" parameter to the server definition. The application should be accessible at http://domain:nginx_port/appname. A more detailed example can be seen in nginx/conf/sample_domain_host.conf. 6.1.4 Using Nginx with Passenger Nginx has been compiled with Phusion Passenger module in Linux and OS X systems. You can use this module to easily deploy a Rails application. In order to do so, you should include the options "passenger_enabled" and specify the root path and rails environment. You can do this adding a new file in nginx/conf/vhosts/apname.conf containing: server { ... root ${rails_appdir}/public; # Path to rails application public dir passenger_enabled on; rails_env production; ... } In this case, it is not necessary to start additional processes appart from Nginx. After restarting Nginx, the application will be accessible at http://domain:nginx_port/. It is also possible to deploy a set of applications to different sub URIs. If you want to use this approach, you should create symbolic links to each application public directory, inside a root path. ln -s /path/to/rails_app/public /websites/phusion/railsapp
ln -s /path/to/rails_app2/public /websites/phusion/railsapp2


Then, include a passenger_base_uri option for each of them inside the server element: server { ... root /websites/phusion; passenger_enabled on; passenger_base_uri /railsapp; passenger_base_uri /railsapp2; ... } After restarting Nginx, the applications will be accessible at http://domain:nginx_port/railsapp/, http://localhots/nginx_port/railsapps2/ .. You can find more information about Phusion Passenger settings at http://www.modrails.com/documentation.html 6.2. CREATING THE FIRST REPOSITORY WITH GIT. Git is an open source version control system designed to handle very large projects with speed and efficiency. 6.2.1. First, we need to run the rubyconsole: cd ~/rubystack-2.0-2 ./rubyconsole 6.2.2. Creating a new repository mkdir my_source_code cd my_source_code git init This will create a new git repository inside the directory my_source_code. 6.2.3 Adding files to the repository Imagine we have a file called sampleproject.txt and we would wish to add it to our repository. Below steps show you how to do this: git add sampleproject.txt git commit sampleproject.txt -m "First version of my project" 6.2.4. Download a copy of an existing repository Say you wish to work on the files in another repository, then you will need to get a copy of that repository. To do so, execute the following command: git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git This will get you a copy of the linux-2.6 source code A directory 'linux-2.6' will now be created. You are now able to modify the files and commit your changes. Please note that you will need permissions to commit your changes to this repository. 6.3 USING RUBY 1.9 WITH THE BITNAMI RUBYSTACK Ruby-1.9 is included into BitNami RubyStack too, in case you wish to use it you should: Linux, OS X: replace scripts/setenv.sh with scripts/setenv19.sh and use rubyconsole19 instead of rubyconsole. Windows: replace scripts\setenv.bat with scripts\setenv19.bat You can rollback to initial ruby version replacing setenv file with setenv18 7. DIRECTORY STRUCTURE The installation process will create several subfolders under the main installation directory: mysql/: MySQL Database. ruby/: Ruby, Rubygems, Rails and SQLite. img/: Additional image files. imagemagick/: ImageMagick image proccessor. license/: License files. subversion/: Subversion revision control system. scripts/: Simple scripts for launching rails applications. sqlite/: SQLite files. Apache2/: Apache2 files. php/: PHP files. apps/phpmyadmin: phpMyAdmin files. memcached/: memcached files. nginx/: nginx files. sphinx/: nginx files. git: git files. 8. TROUBLESHOOTING In addition to the resources provided below, we encourage you to post your questions and suggestions at: http://bitnami.org/forums/ We also encourage you to sign up for our newsletter, which we'll use to announce new releases and new stacks. To do so, just register at: http://www.bitnami.org/catalog/newsletter. 8.1 Installer # Installer Payload Error If you get the following error while trying to run the installer from the command line: "Installer payload initialization failed. This is likely due to an incomplete or corrupt downloaded file" The installer binary is not complete, likely because the file was not downloaded correctly. You will need to download the file and repeat the installation process. 8.2 MySQL The following are some common problems: # Access denied when trying to connect to MySQL. If you get an Access Denied message while trying to connect to MySQL, make sure you are using the correct username and password. # "Can't connect to server" message. Make sure that the MySQL daemon is up and running. Remember also that if during installation you selected a different listening port for MySQL, you may need to pass that as an extra command line option. For help in troubleshooting MySQL errors, you may want to reference the "Problems and Common Errors" section of the MySQL manual, which you will find at http://dev.mysql.com/doc/ 8.3 Apache If you find any problem starting Apache, the first place you should check is the Apache error log file: /home/user/drupal/apache2/logs/error.log on Linux and OS X or C:\Program Files\BitNami RubyStack\apache2\logs\error.log on Windows. Most errors are related to not being able to listen to the default port. Make sure there are no other server programs listening at the same port before trying to start Apache. Some programs, such as Skype, may also use port 80. For issues not covered in this Quick Start guide, please refer to the Apache documentation, which is located at http://httpd.apache.org/docs/ 9. LICENSES MySQL is distributed under the GNU General Public License v2, which is located at http://www.gnu.org/licenses/old-licenses/gpl-2.0.html Ruby is released under the Ruby License and GPL, wich is located at http://www.ruby-lang.org/en/LICENSE.txt Rails is released under the MIT license, which is located http://www.opensource.org/licenses/mit-license.php Apache Web Server is distributed under the Apache License v2.0, which is located at http://www.apache.org/licenses/LICENSE-2.0 PHP and related libraries are distributed under the PHP License v3.01, which is located at http://www.php.net/license/3_01.txt phpMyAdmin is distributed under the GNU General Public License v2, which is located at http://www.gnu.org/licenses/old-licenses/gpl-2.0.html Git is released under the GNU General Public License v2, which is located at http://www.gnu.org/licenses/old-licenses/gpl-2.0.html Subversion is released under Subversion License / released under the terms of the Apache License, which is located at http://subversion.tigris.org/license-1.html RubyGems is released under the Ruby License, which is located at http://www.ruby-lang.org/en/LICENSE.txt Rake is released under the Ruby License, which is located at http://www.ruby-lang.org/en/LICENSE.txt Mongrel Web Server (Mongrel) is released under the Ruby License, which is located at http://www.ruby-lang.org/en/LICENSE.txt Nginx is released under 2-clause BSD-like license, which is located at http://nginx.org/LICENSE Sphinx is released under the GNU General Public License v2, which is located at http://www.gnu.org/licenses/old-licenses/gpl-2.0.html Capistrano is released under the MIT/X Consortium License, which is located at http://dev.rubyonrails.org/browser/tools/capistrano/MIT-LICENSE?rev=5270 SQLite is released under the Public Domain license, which is located at http://en.wikipedia.org/wiki/Public_Domain ImageMagick has its own license, which is located at https://www.imagemagick.org/subversion/ImageMagick/trunk/LICENSE Rmagick is released under the MIT license, which is located at http://www.opensource.org/licenses/mit-license.php OpenSSL is released under the terms of the Apache License, which is located at http://www.openssl.org/source/license.html Zlib is released under the zlib License (a free software license/compatible with GPL), which is located at http://www.gzip.org/zlib/zlib_license.html Libiconv is released under the LGPL license, which is located at http://www.gnu.org/licenses/lgpl.html