====== Apache ======
Brightboxes use the Apache web server by default.  The Brightbox Capistrano recipes do things in a certain way, such as writing logs to a particular place.  We recommend you follow the same guidelines if you do manual configuration to get the most benefit of the Brightbox setup - of course you're free to do things how you wish.

===== Configuration =====
The Brightbox gem configures your Rails sites in Apache with a separate file for each app and we recommend you do the same if doing it manually.  Create a new file ''/etc/apache2/sites-available/rails-myapp''.  A skeleton config might look like this:
<code apache>
<VirtualHost *:80>
  ServerName username-001.vm.brightbox.net
  ServerAlias www.mydomain.co.uk

  DocumentRoot /home/rails/myapp/current/public

  <Directory "/home/rails/myapp/current/public">
    Options FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
  </Directory>

  # Configure mongrel_cluster
  <Proxy balancer://mongrel_cluster>
    BalancerMember http://127.0.0.1:9200
    BalancerMember http://127.0.0.1:9201
  </Proxy>

  ErrorLog /var/log/web/myapp.err
  CustomLog /var/log/web/myapp.log combined

  # Rails specific rewrite rules
  Include /etc/apache2/brightbox-common
</VirtualHost>
</code>

When you're ready to deploy the config, symlink it into the ''sites-enabled'' directory and reload Apache.  There is a script to do the symlinking for you, which takes the name of the new config file you created.
<code bash>
a2ensite rails-myapp
/etc/init.d/apache2 reload
</code>


==== Logging and log rotation ====
We recommend writing your Apache logs into the ''/var/log/web/'' directory.  Error log files as ''*.log'' and access logs just as ''*.log''.  The default Brightbox log rotation config will rotate these logs weekly, compressing them as it does.  It keeps 52 weeks of logs by default.  This can be changed by editing the ''/etc/logrotate.d/apache2'' config.

The Brightbox gem prior to version 0.24 put your logs in ''/var/log/apache2'' by default.  Since then they are put in ''/var/log/web''.

==== Controlling access using Apache ====
Due to the way Apache hands off Rails processing to the Mongrel servers, you can't put Limit directives in a ''.htaccess'' file.

The easiest way to control access to your Rail app with Apache is to add a ''Location'' section '''after''' the ''brightbox-common'' include directive in the Apache config for your app (''/etc/apache2/sites-enabled/rails-myapp'' by default):

<code apache>
  ErrorLog /var/log/web/myapp.err
  CustomLog /var/log/web/myapp.log combined

  # Rails specific rewrite rules
  Include /etc/apache2/brightbox-common

  <Location />
    Allow from 70.84.143.109
    Deny from all
  </Location>

</VirtualHost>
</code>

==== Multiple domains ====
To have a ''VirtualHost'' respond to more than one domain, just add a ''ServerAlias'' line to your app's config file (see above for where that is), specifying any additional domains you want to be handled:

<code apache>
<VirtualHost *:80>
  ServerName www.example.co.uk
  ServerAlias example.co.uk www.example.com www.example.org
</code>

And reload Apache.



==== Configuring SSL ====

Create the file ''/etc/apache2/conf.d/ssl.conf'' with the following:
<code apache>
Listen 443
NameVirtualHost *:443

# Strengthen the SSL protocol to current recommendations.
SSLProtocol all -SSLv2
SSLCipherSuite HIGH:MEDIUM:!aNULL:+SHA1:+MD5:+HIGH:+MEDIUM
SSLOptions +StrictRequire
</code>

Then create a new site config ''/etc/apache2/sites-available/rails-myapp-ssl''.  Configure it like any other site (if you've previously deployed using the gem, you can copy the config created by that) but modify it too look more like this:

<code apache>
<VirtualHost *:443>
  SSLEngine On
  SSLCertificateFile /etc/apache2/mycert.pem
  SSLCertificateKeyFile /etc/apache2/mykey.key

  # Make sure that Rails knows this request came via https
  RequestHeader set X_FORWARDED_PROTO 'https'

  # Document root, proxy balancer stuff, etc.etc. goes here

  # Rails specific rewrite rules
  Include /etc/apache2/brightbox-common
</VirtualHost>
</code>

Ensure that your key file is owned by root and has the permissions ''0600''.

Then enable the new site config, enable mod_ssl, enable mod_headers, check the configs and reload Apache:

<code>
# a2ensite rails-myapp-ssl
  Site rails-myapp-ssl installed; run /etc/init.d/apache2 reload to enable.

# a2enmod ssl
  Module ssl installed; run /etc/init.d/apache2 force-reload to enable.

# a2enmod headers
  Module headers installed; run /etc/init.d/apache2 force-reload to enable.

# apache2ctl -t
  Syntax OK

# /etc/init.d/apache reload
  * Reloading web server config... [ ok ]
</code>