h1. Setting up Nginx + Passenger 

Passenger packages/repos are available at http://passenger.stealthymonkeys.com/

h2. Nginx + Passenger with foreman on CentOS

Install packages

<pre>

    # yum install -y nginx-passenger

</pre>

Create self signed certificate

<pre>

    # cd /etc/nginx/

    # openssl genrsa -des3 -out server.key 1024

    # openssl req -new -key server.key -out server.csr

    # cp server.key server.key.org

    # openssl rsa -in server.key.org -out server.key

    # openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

</pre>

Make a local copy of the apps `public` directory (local to rails, as nginx/passenger doesn't seem to like symbolic links)

<pre>

    # cd /usr/share/foreman

    # rm public

    # cp -a /var/lib/foreman/public .

</pre>

Add to `/etc/nginx/nginx.conf`:

<pre>

    env PATH;

</pre>

Create foreman application config file `/etc/nginx/conf.d/foreman.conf`:

<pre>

    server {

        listen 443;

        server_name _;

        ssl on;

        ssl_certificate /etc/nginx/server.crt;

        ssl_certificate_key /etc/nginx/server.key;

        # Verify puppetmaster clients against Puppet CA

        ssl_crl /var/lib/puppet/ssl/ca/ca_crl.pem;

        ssl_client_certificate /var/lib/puppet/ssl/certs/ca.pem;

        ssl_verify_client optional;

        ssl_verify_depth 1;

        access_log /var/log/nginx/foreman_access.log;

        error_log /var/log/nginx/foreman_error.log debug;

        root /usr/share/foreman/public;

        passenger_enabled on;

        passenger_set_cgi_param HTTPS on;

        passenger_set_cgi_param SSL_CLIENT_S_DN $ssl_client_s_dn;

        passenger_set_cgi_param SSL_CLIENT_VERIFY $ssl_client_verify;

        # If using Passenger 5 then something similar to the following should be used, and the corresponding values updated in Settings/Authentication:

        # passenger_env_var HTTPS on;

        # passenger_set_header X-Client-DN $ssl_client_s_dn;       # Set to HTTP_X_CLIENT_DN

        # passenger_set_header X-Client-Verify $ssl_client_verify; # Set to HTTP_X_CLIENT_VERIFY

        #location / {

        #}

    }

</pre>

The SSL configuration here can verify clients for SSL communications with puppetmaster scripts, as per the "Securing Communications with SSL":http://theforeman.org/manuals/1.1/index.html#5.4SecuringCommunicationswithSSL documentation.  It verifies clients using the Puppet CA and passes the information to Passenger and Foreman.

This guide uses a self-signed certificate for the Foreman server, so the ENC and report scripts will need to reference the certificate generated here in the @:ssl_ca@ and @$foreman_ssl_ca@ settings.

h2. Nginx + Passenger with foreman 1.2 on RHEL6.x/Scientific Linux

To run both puppermaster and foreman 1.2 on the same host using nginx + passenger an upgrade to phusion passenger 4.0 is required. To not break your existing puppetmaster setup, which uses the system supplied ruby follow the following steps:

setup assumes you are upgrading from foreman 1.1 and have a working nginx-passenger setup already.

<pre>

the current phusion supplied rpm is still a 3 version, so using yum upgrade won't help

yum info passenger-release

Loaded plugins: security

Available Packages

Name        : passenger-release

Arch        : noarch

Version     : 3

Release     : 6.el6

Size        : 5.5 k

Repo        : passenger

Summary     : Phusion Passenger release RPM/Yum repository configuration

URL         : http://passenger.stealthymonkeys.com/

License     : MIT

Description : Phusion Passenger Yum/RPM configuration. This package contains the Yum

            : repository configuration to install & update Phusion Passenger, as

            : well as the GPG signing key to verify them.

</pre>

So instead use gem to install the correct package (as per: https://www.phusionpassenger.com/download#open_source):

<pre>

gem install passenger

Fetching: daemon_controller-1.1.4.gem (100%)

Fetching: passenger-4.0.5.gem (100%)

Successfully installed daemon_controller-1.1.4

Successfully installed passenger-4.0.5

2 gems installed

Installing ri documentation for daemon_controller-1.1.4...

Installing ri documentation for passenger-4.0.5...

Installing RDoc documentation for daemon_controller-1.1.4...

Installing RDoc documentation for passenger-4.0.5...

</pre>

Configure nginx:

you might need to install some packages ( yum install libcurl-devel libcurl )

<pre>

passenger-install-nginx-module

Welcome to the Phusion Passenger Nginx module installer, v4.0.5.

This installer will guide you through the entire installation process. It

shouldn't take more than 5 minutes in total.

Here's what you can expect from the installation process:

 1. This installer will compile and install Nginx with Passenger support.

 2. You'll learn how to configure Passenger in Nginx.

 3. You'll learn how to deploy a Ruby on Rails application.

Don't worry if anything goes wrong. This installer will advise you on how to

solve any problems.

Press Enter to continue, or Ctrl-C to abort.

--------------------------------------------

Checking for required software...

 * Checking for GNU C compiler...

      Found: yes

      Location: /usr/bin/gcc

 * Checking for GNU C++ compiler...

      Found: yes

      Location: /usr/bin/g++

 * Checking for A download tool like 'wget' or 'curl'...

      Found: yes

      Location: /usr/bin/wget

 * Checking for Ruby development headers...

      Found: yes

      Location: /usr/lib64/ruby/1.8/x86_64-linux/ruby.h

 * Checking for OpenSSL support for Ruby...

      Found: yes

 * Checking for RubyGems...

      Found: yes

 * Checking for Rake (associated with /usr/bin/ruby)...

      Found: yes

      Location: /usr/bin/ruby /usr/bin/rake

 * Checking for rack...

      Found: yes

 * Checking for Curl development headers with SSL support...

      Found: yes

      Version: libcurl 7.19.7

      Usable: yes

      curl-config location: /usr/bin/curl-config

      Supports SSL: yes

      Header location: /usr/include/curl/curl.h

 * Checking for OpenSSL development headers...

      Found: yes

      Location: /usr/include/openssl/ssl.h

 * Checking for Zlib development headers...

      Found: yes

      Location: /usr/include/zlib.h

</pre>

Stop nginx and update /etc/init.d/nginx to use the correct binary

<pre>

vi /etc/init.d/nginx

#nginx="/usr/sbin/nginx"

nginx="/opt/nginx/sbin/nginx"

</pre>

Make sure passenger.conf in /etc/nginx/conf,d still points to the system ruby passenger version

<pre>

# cat passenger.conf

passenger_root /usr/lib/ruby/gems/1.8/gems/passenger-4.0.5;

passenger_ruby /usr/bin/ruby;

</pre>

Update foreman.conf (do not set the passenger_root)

<pre>

 # cat foreman.conf

server {

  passenger_ruby /usr/bin/ruby193-ruby;

  .....

}

 <snip>

</pre>

Start nginx and check if the website is working now.

h2. Post-install setup for Foreman 1.1+ to support certificate authentication via Nginx

Starting from Foreman 1.1 it requires a bit more configuration because by default it supports only Apache webserver environment but Foreman also provides a configuration to make it fit to any other webserver.

Log in to the administration area and go to Administer -> Setting page. Find *ssl_client_dn_env* variable and set its value to @HTTP_X_CLIENT_DN@ . Also find *ssl_client_verify_env* and set it to @HTTP_X_CLIENT_VERIFY@ . 

These modifications are required since nginx behaves a bit different than Apache and passes SSL certificate informations on different way.

If you plan to use Nginx for Puppet Master too, check the corresponding variables in puppet.conf: *ssl_client_header* and *ssl_client_verify_header*

http://www.modrails.com/documentation/Users%20guide%20Nginx.html#_configuring_phusion_passenger has more information