Please review the installation docs

[Hongli Lai]

Hi Phusion Passenger users,

As you may have noticed we've completely rewritten in the installation
section of the manual. The old installation manual was deemed
inadequate because it wasn't complete enough. Every component that
Phusion Passenger depends on (Ruby, Apache, compiler, etc) can be
installed and configured in a myriad of ways and cause confusion. The
new installation section aims to be easy to follow even for newcomers,
but at the same time also complete. It aims to covers RVM, situations
in which Ruby may or may not be installed as root, situations in which
permissions are not correct and need to be fixed, different Apache
configuration file locations, installation through YUM and APT,
installation for people who are not familiar with Ruby, etc.

We would like to ask people to read the new installation docs with a
critical eye. Is it truly better now? Is it easy to follow for
newcomers? Does it handle all cases and all edge cases? If you run
into a problem during installation, does the manual properly help you?
Feedback is much appreciated.

You can find the newest docs here:
http://www.modrails.com/documentation/Users%20guide%20Apache.html
http://www.modrails.com/documentation/Users%20guide%20Nginx.html

You can find the previous docs here:
http://www.modrails.com/documentation/Users%20guide%20Apache%203.0.html
http://www.modrails.com/documentation/Users%20guide%20Nginx%203.0.html

--
Phusion | Ruby & Rails deployment, scaling and tuning solutions

Web: http://www.phusion.nl/
E-mail: in...@phusion.nl
Chamber of commerce no: 08173483 (The Netherlands)

[Luke Holder]

Thanks for this upgrade.

Can i suggest instructions on installation into a cpanel managed environment would boost your install base substantially.

Regards,

Luke Holder.

[Karuna Murti]

1. Still using ubuntu hardy on the documentation? It's 4 years old operating system. You might want to replace ubuntu with debian since debian provide official package for passenger.

2. On ubuntu / debian based system the location the proper place for LoadModule passenger_module /path/to/mod_passenger.so should be on /etc/apache2/mods-available/passenger.load, the proper place for passenger configuration should be in /etc/apache2/mods-available/passenger.conf

<IfModule mod_passenger.c>

  PassengerRoot /path/to/gem/folder/

  PassengerRuby /path/to/ruby

  #other passenger module configuration

</IfModule>

User can enable apache module by using command a2enmod passenger and disable apache module by using command a2dismod

[Hongli Lai]

On Tue, Jan 29, 2013 at 4:46 PM, Karuna Murti <karuna...@gmail.com> wrote:
> 1. Still using ubuntu hardy on the documentation? It's 4 years old operating
> system. You might want to replace ubuntu with debian since debian provide
> official package for passenger.

Ah I see that the Brightbox instructions were out of date. I've
updated the instructions. I'll also check whether they have a Debian 6
compatible repo so that we can advocate that as the preferred repo for
Debian 6 users.

We don't make mention of the official Debian packages because they
tend to be out of date.

> 2. On ubuntu / debian based system the location the proper place for
> LoadModule passenger_module /path/to/mod_passenger.so should be on
> /etc/apache2/mods-available/passenger.load, the proper place for passenger
> configuration should be in /etc/apache2/mods-available/passenger.conf
>
> <IfModule mod_passenger.c>
> PassengerRoot /path/to/gem/folder/
> PassengerRuby /path/to/ruby
> #other passenger module configuration
> </IfModule>
>
> User can enable apache module by using command a2enmod passenger and disable
> apache module by using command a2dismod

Documentation for this has been added.

[Karuna Murti]

My review for nginx.

Removing nginx from system package means removing init script that comes with system nginx.

I know it's probably not the scope of the documentation, but it will help users a lot if you can show how to add init script for nginx after installing passenger + nginx.

http://wiki.nginx.org/Nginx-init-ubuntu

http://stackoverflow.com/questions/8019651/init-d-script-for-nginx-on-cent-os

http://wiki.nginx.org/RedHatNginxInitScript

[Hongli Lai]

Alright, I've added a section for this.

On Wed, Jan 30, 2013 at 4:42 AM, Karuna Murti <karuna...@gmail.com> wrote:
> My review for nginx.
> Removing nginx from system package means removing init script that comes
> with system nginx.
> I know it's probably not the scope of the documentation, but it will help
> users a lot if you can show how to add init script for nginx after
> installing passenger + nginx.
>
> http://wiki.nginx.org/Nginx-init-ubuntu
> http://stackoverflow.com/questions/8019651/init-d-script-for-nginx-on-cent-os
> http://wiki.nginx.org/RedHatNginxInitScript

[Karuna Murti]

Btw, I still see REE mentioned in the documentation. Can you add REE for 1.8.7 and 1.9.3 / 2.0.0 ?

[Rick Schmitty]

Here are my takes - given as a point of view from someone new to Ruby and very new to Passenger (only have tried the beta so far).  I've read the entire guide as I'm excited about the new release and want to try and grasp as much as possible :)

http://www.modrails.com/documentation/Users%20guide%20Apache.html#_where_to_get_support

I saw you guys are on GitHub as well, will future Issues be sent there or remain at google code?  Might be helpful to add to the README.md pointing to the google code issues and/or adding to this document section explaining what each repository is to be used for


http://www.modrails.com/documentation/Users%20guide%20Apache.html#rubygems_generic_install

You had previously answered my question on this, might be worth including a sentence that if you plan on running multiple ruby versions you don't need to gem install passenger for each ruby as it is simply there to install to apache/nginx


Step 3: add the RubyGems bin directory to your $PATH

"If you all the following are applicable to you:" should be "If all of" ?


http://www.modrails.com/documentation/Users%20guide%20Apache.html#_installing_or_upgrading_on_debian_6_or_ubuntu

References Nginx installation in the Apache guide.  Nginx was referenced in other places as well.  Not sure if the goal of the 2 guides is to completely remove references to the other server


http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerRuby

Not sure of the way to get the bin path in RVM, but users using rbenv can run `rbenv which ruby` to get the bin path of the ruby version.  If you simply type `which ruby` you will only get your current shimmed ruby which wont work with passenger


http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerSpawnMethod

It was slightly confusing to see the other options there with a callout to "leave it at smart-lv2" as well as the default value of "smart-lv2"

Personally I would put the note "As of Passenger 3.2...[this stuff was renamed]" note at the top and reword it towards older customers so all future text uses 3.2+ terminology. 


http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerrestartdir_lt_directory_gt

What does a global server config do? Does it restart all applications?  Everything seems to reference a single application.  For example what would happen if I set in the global config `PassengerRestartDir /restart_files` ?


http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerfriendlyerrorpages_lt_on_off_gt

Out of scope for this email, but can you customize this page? For example pointing it to your public/500.html?


http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengermaxpoolsize_lt_integer_gt

It might be worth explaining or showing the rule of thumb calculation so people with other ram ammounts can have a starting point - or an explanaition why you shouldnt start with more than 15 for for systems with more ram

re the note below: Is Ruby Enterprise only an alternative to ruby 1.8, as in no such alternative exists for 1.9?


"This feature is only available in Phusion Passenger Enterprise. It was introduced in version 3.0.0. Buy Phusion Passenger Enterprise here."

In each section it says what the default value is for Enterprise.  Does this mean the open source version is also defaulted to that value and you cannot change it, or does open source behave in a different way?  May be worth noting how open source version behaves for each of these sections.  If it's not worth noting I'd still like to know for myself :)


http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerstatthrottlerate_lt_integer_gt

Might be helpful to hyperlink `always_restart.txt` to the section below.  This was the first time I saw that file referenced and had no immediate explanation as to how its always going to be restarting


http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerHighPerformance

Are there any _required_ apache modules for a typical rails app?  Obviously I should test, but as a new rails user, and newer to rails with apache, I have no idea what is needed outside of installing passenger.


Anywho, thats all I got.  Also learned all the nice stuff in Enterprise version by reading this document, looking forward to the release

[Hongli Lai]

On Mon, Feb 18, 2013 at 1:53 PM, Rick Schmitty <flex...@gmail.com> wrote:
> Here are my takes - given as a point of view from someone new to Ruby and
> very new to Passenger (only have tried the beta so far). I've read the
> entire guide as I'm excited about the new release and want to try and grasp
> as much as possible :)

Great, a fresh pair of eyes are always welcome. :)

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#_where_to_get_support
>
> I saw you guys are on GitHub as well, will future Issues be sent there or
> remain at google code? Might be helpful to add to the README.md pointing to
> the google code issues and/or adding to this document section explaining
> what each repository is to be used for

Google Code is only used for the issue tracker, and perhaps for
hosting some beta downloads. Everything else is on Github. The Github
issue tracker has been turned off to avoid confusion. In the future we
may or may not move to Github Issues.

But I don't understand what you find confusing about the documentation
regarding this point. The only link to Google Code says that it's used
for bug tracking. Do you have a suggestion on how it can be improved?

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#rubygems_generic_install
>
> You had previously answered my question on this, might be worth including a
> sentence that if you plan on running multiple ruby versions you don't need
> to gem install passenger for each ruby as it is simply there to install to
> apache/nginx

This has already been added to the documentation, but not yet
published on the website. :)

> Step 3: add the RubyGems bin directory to your $PATH
>
> "If you all the following are applicable to you:" should be "If all of" ?

Fixed.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#_installing_or_upgrading_on_debian_6_or_ubuntu
>
> References Nginx installation in the Apache guide. Nginx was referenced in
> other places as well. Not sure if the goal of the 2 guides is to completely
> remove references to the other server

The goal is for each guide to refer only to the server it's meant to.
Sometimes I'm lazy and didn't bother to write the 'ifdef'. I'll take
note of this.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerRuby
>
> Not sure of the way to get the bin path in RVM, but users using rbenv can
> run `rbenv which ruby` to get the bin path of the ruby version. If you
> simply type `which ruby` you will only get your current shimmed ruby which
> wont work with passenger

Yes, RVM users need to point to the wrapper script. I'll ask the RVM
authors whether there's a nice command for printing the path to the
wrapper script.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerSpawnMethod
>
> It was slightly confusing to see the other options there with a callout to
> "leave it at smart-lv2" as well as the default value of "smart-lv2"
>
> Personally I would put the note "As of Passenger 3.2...[this stuff was
> renamed]" note at the top and reword it towards older customers so all
> future text uses 3.2+ terminology.

Ah yes. The spawning options for Phusion Passenger 4 have been
significantly changed but the documentation is lagging behind. I'll
work on this.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerrestartdir_lt_directory_gt
>
> What does a global server config do? Does it restart all applications?
> Everything seems to reference a single application. For example what would
> happen if I set in the global config `PassengerRestartDir /restart_files` ?

Yes, it would restart all apps because all apps will look in that
directory for a changed restart.txt.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerfriendlyerrorpages_lt_on_off_gt
>
> Out of scope for this email, but can you customize this page? For example
> pointing it to your public/500.html?

Not at the time.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengermaxpoolsize_lt_integer_gt
>
> It might be worth explaining or showing the rule of thumb calculation so
> people with other ram ammounts can have a starting point - or an
> explanaition why you shouldnt start with more than 15 for for systems with
> more ram

Yes. We're already working on an article that explains this better.

> re the note below: Is Ruby Enterprise only an alternative to ruby 1.8, as in
> no such alternative exists for 1.9?

No such alternative exists for 1.9. Ruby Enterprise Edition has been
End-of-Life'd since last year so we should remove all references to it
anyway. The way forward w.r.t. saving memory is to use multithreading
which we support in Phusion Passenger Enterprise.

> "This feature is only available in Phusion Passenger Enterprise. It was
> introduced in version 3.0.0. Buy Phusion Passenger Enterprise here."
>
> In each section it says what the default value is for Enterprise. Does this
> mean the open source version is also defaulted to that value and you cannot
> change it, or does open source behave in a different way? May be worth
> noting how open source version behaves for each of these sections. If it's
> not worth noting I'd still like to know for myself :)

If a section is marked "This feature is only available in Phusion
Passenger Enterprise" then it means that the feature is not available
in the open source version. Trying to use the feature in the open
source version will result in an error message.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#_passengerstatthrottlerate_lt_integer_gt
>
> Might be helpful to hyperlink `always_restart.txt` to the section below.
> This was the first time I saw that file referenced and had no immediate
> explanation as to how its always going to be restarting

Good point. I've taken note of this.

> http://www.modrails.com/documentation/Users%20guide%20Apache.html#PassengerHighPerformance
>
> Are there any _required_ apache modules for a typical rails app? Obviously
> I should test, but as a new rails user, and newer to rails with apache, I
> have no idea what is needed outside of installing passenger.

No. Phusion Passenger and Rails work even with the bare minimum.

The current manual kind of assumes that the user already knows Apache
well, but it looks like this assumption is often not correct. It would
be good if the manual tries better to attend to Apache newbies.

> Anywho, thats all I got. Also learned all the nice stuff in Enterprise
> version by reading this document, looking forward to the release

Thanks for all your feedback. If there's anything else, please let us know. :)

With kind regards,
Hongli Lai

[Rick Schmitty]

Thanks for all the responses!

You are right on the Google Code part.  That section is clear as to where to get support.  I guess when I originally found passenger and saw both Google Code and the GitHub account I wasn't sure which had the "latest and greatest"


Phusion Passenger Enterprise only stuff: I guess what I'm asking is, is it safe to assume that the default value of the Enterprise edition is what the open source version will "use" (even though we won't be explicitly using it in a config).  The on|off variables obviously would be "off" since they aren't in open source at all, but for the following:

PassengerMemoryLimit: In open source is there any memory limit to an application (like 200 the default in Enteprise) or will a bad application leak memory until all is consumed?
PassengerConcurrencyModel:  What is the modal used by open source?  I'm assuming process


For the PassengerHighPerformance.  I didn't mean to come across as not knowing some apache, more that I don't know how rails/passenger works with apache.  To me I would guess most vanilla rails apps don't need mod_rewrite or mod_autoindex.  However, again, I'm new to rails and passenger. The "other Apache modules" from "If you do not use mod_rewrite or other Apache modules then it might make sense to enable high performance mode" is where I was leery.  Is there a list of known incompatibilities or known compatibilities? mod_ssl, mod_deflate, etc?

I guess this sticks out like a "Turbo" button on the old x386.  I never really knew what programs needed it off and just think faster is better by default and I want that on!


Thats all, again thank you!