====== Adding SSL support for Apache ======

You can tell the Brightbox gem to setup an SSL configuration for your application in Apache, by giving it the name of an installed SSL certificate.





===== Adding the certificate =====

The simplest way is to set the ''ssl_certificate'' variable, e.g:
<code>
set :ssl_certificate, "brightbox"
</code>

This will look for a certificate called ''brightbox.crt'' in the directory ''/etc/ssl/certs'' and a private key called ''brightbox.key'' in the directory ''/etc/ssl/private''. These are the default locations for openssl certificates on Ubuntu.

You can be more specific: 
<code>
set :ssl_certificate, "/etc/apache2/ssl/my_cert.pem"
set :ssl_key, "/etc/apache2/ssl/my_cert.key"
</code>

==== Password Encrypted Private Keys ====

Using a private key that's encrypted using a password prevents apache from restarting without intervention, for instance after a reboot. To prevent this, upload a copy of the key that isn't protected with a password.


===== Intermediate certificate =====

If the certificate you have bought requires an 'intermediate certificate' or certificate chain (GoDaddy requires this) then depending on which Brightbox deployment gem version you have there's a couple of ways to do this.

**Deployment Gem version 2.3.6 or above**

You can set the intermediate certificate in the same way as the SSL Certificate above. Either specify the certificate name and the gem will look in ''/etc/ssl/certs'' for it.

<code>
set :ssl_intermediate, "inter.crt"
</code>

Or you can be more specific and define where the certificate is on the filesystem:

<code>
set :ssl_intermediate, "/etc/apache2/ssl/inter.crt"
</code>

**Deployment Gem version 2.3.5 or below**

You'll need to manually add a link to this file into your vhost file after you have run ''cap deploy:initial''. Note that this setting will be wiped out on subsequent runs of ''deploy:initial''. Below is an example of using the SSLCertificateChainFile directive to link your intermediate bundle to your certificate.

<code apache>
<VirtualHost _default_:443>
  SSLEngine On
  SSLCertificateFile /etc/ssl/certs/my.crt
  SSLCertificateKeyFile /etc/ssl/private/my.key
  SSLCertificateChainFile /etc/ssl/certs/intermediate_bundle.crt
</code>

===== Creating the configuration =====

When you run, or rerun ''deploy:setup'', the gem will detect that ''ssl_certificate'' is set and will create an Apache configuration called ''rails-default-ssl''.

In practice you can only have one SSL site per IP on a web server, so to add additional SSL sites you need additional IP addresses.

Our deployment gem currently only supports one SSL site per Brightbox.  If you need to configure multiple SSL sites per Brightbox then you'll need to configure Apache manually, with each SSL site configured to listen on  different IPs.

With [[http://en.wikipedia.org/wiki/Server_Name_Indication|Server Name Indication]] you can have multiple SSL sites on a single IP address, but this doesn't work in all browsers.