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.


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:

<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
  # Configure mongrel_cluster
  <Proxy balancer://mongrel_cluster>
  ErrorLog /var/log/web/myapp.err
  CustomLog /var/log/web/myapp.log combined
  # Rails specific rewrite rules
  Include /etc/apache2/brightbox-common

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.

a2ensite rails-myapp
/etc/init.d/apache2 reload

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):

  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
    Deny from all

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:

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

And reload Apache.

Wildcard domains

To have a VirtualHost respond to a wild card domain (*.example.com), just add a ServerAlias entry for the wild card domain.

<VirtualHost *:80>
  ServerName www.example.com
  ServerAlias *.example.com

Note: You cannot set your ServerName to be a wild card domain, it must always be a full domain name such as www.example.com

Configuring SSL

Create the file /etc/apache2/conf.d/ssl.conf with the following:

Listen 443
NameVirtualHost *:443
# Strengthen the SSL protocol to current recommendations.
SSLProtocol all -SSLv2
SSLOptions +StrictRequire

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:

<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

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:

# 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 ]

Configuring HTTP basic authentication

If you are developing a site that you would like to protect from the outside world then you can enable http basic authentication within Apache.

You'll need to create a htpasswd file using the Apache htpasswd utility.

# htpasswd -c /etc/apache2/password_file mruser
New password: mypassword
Re-type new password: mypassword

For any additional user omit the -c flag

# htpasswd /etc/apache2/password_file anotheruser
New password: mypassword
Re-type new password: mypassword

Once the password file is created you can add a set of directives into your vhost configuration to require a valid user from this file before allowing access.

AuthType Basic
AuthName "Restricted Files"
AuthUserFile /etc/apache2/password_file
Require user mruser

More information is available on the Apache documentation site

docs/apache.txt · Last modified: 2009/05/08 17:04 (external edit)