almost effortless

These instructions require and assume the following:

• You're running Debian Lenny and you've got root access
• You've got a functioning apache2 installation
• You know the basics of working on the command line (i.e. how to edit files, execute commands, etc.)

If the above is true of your situation, read on to learn how to install Ruby Enterprise, Phusion Passenger and El Dorado from scratch in a sort of "one-off" setting where you've got one server and you want it to run one site.

NB: These instructions don't use git or capistrano. The instructions contained in the El Dorado README describe how to install El Dorado using those tools. Using them makes for an easier and cleaner installation. It also makes for easier scalability, upgrading and patching: I highly recommend using those tools.

1. Resolve Dependencies

The first thing you'll need to do, even before installing RE or PP, is make sure that you've got the development files for the databases that RE and PP applications use:

apt-get install libsqlite3-ruby postgresql-8.3-plruby libmysql-ruby libmysqlclient15-dev postgresql-server-dev-8.3 libsqlite3-dev

If you don't resolve these dependencies now, you'll get a message during the RE installation that prompts you to install gems for mysql, postgres, etc. and then, when you go to install those gems, you'll get an error like this:

ERROR:  Error installing mysql:
	ERROR: Failed to build gem native extension.

So just go ahead and resolve those dependencies in advance.

2. Install Ruby Enterprise

The best practice for this, as far as I know, is to install the current stable release of RE in /opt/. First, download the release you plan to use:

lana:~# cd /opt
lana:/opt# wget http://rubyforge.org/frs/download.php/58677/ruby-enterprise-1.8.6-20090610.tar.gz

Once that's down, untar it and execute the installer script:

lana:/opt# tar -zxvf ruby-enterprise-1.8.6-20090610.tar.gz
[...]
lana:/opt# cd ruby-enterprise-1.8.6-20090610/
lana:/opt/ruby-enterprise-1.8.6-20090610# ./installer

That should run, after a few tappings of ye olde Enter key, to its error-free conclusion. If, during the installation, the installer finds that you're missing software packages, the installer will bail and you'll be given some commands that fill those holes. Resolve those dependencies and finish the installation.

At the end of the installation, you'll be given some syntax that will automatically install PP. You'll use that in the next step.

3. Install Phusion Passenger

Use the automatically generated syntax:

lana:/opt/ruby-enterprise-1.8.6-20090610# /opt/ruby-enterprise-1.8.6-20090610/bin/passenger-install-apache2-module

Again, the installer will bail and prompt you to resolve dependencies if you've got any:

Installation instructions for required software

 * To install Apache 2 development headers:
   Please run apt-get install apache2-prefork-dev as root.

 * To install Apache Portable Runtime (APR) development headers:
   Please run apt-get install libapr1-dev as root.

 * To install Apache Portable Runtime Utility (APU) development headers:
   Please run apt-get install libaprutil1-dev as root.

Resolve dependencies and finish the installation.

Once it's finished, you'll be given some lines to add to your "Apache configuration file". The best file to add these lines to is /etc/apache2/httpd.conf.

Just don't forget that you added them there (as opposed to somewhere else), as you'll need to modify them if you upgrade RE.

You'll also probably want to go ahead and add the following lines while you've got the file open:

PassengerPoolIdleTime 14400
PassengerMaxInstancesPerApp 2

Those lines do exactly what it looks like they do. They're also very sensible settings to start with, as they'll prevent El Dorado from hogging a bunch of system resources, etc. right off the bat.

You can find more information here.

Finally, your /etc/apache2/httpd.conf file should look something like this:

PassengerPoolIdleTime 14400
PassengerMaxInstancesPerApp 2

LoadModule passenger_module /opt/ruby-enterprise-1.8.6-20090610/lib/ruby/gems/1.8/gems/passenger-2.2.4/ext/apache2/mod_passenger.so
PassengerRoot /opt/ruby-enterprise-1.8.6-20090610/lib/ruby/gems/1.8/gems/passenger-2.2.4
PassengerRuby /opt/ruby-enterprise-1.8.6-20090610/bin/ruby

Once you've made those changes, you're ready to begin installing El Dorado.

When it exits, the PP installer will show you some sample syntax for how to write an apache configuration file for your first application. You can ignore that for now, as we're going to come back to it later.

4. Install El Dorado

First, get the latest release of the software from Trevor's github: http://github.com/trevorturk/eldorado/tree/master

Once you've got the URL of the latest release, switch from root to a less privileged user, make a folder in your home dir for the site, download the latest release of El Dorado to that directory and untar it:

toconnell@lana:~$ mkdir example.com
toconnell@lana:~$ cd example.com
toconnell@lana:~/example.com$ wget wget http://download.github.com/trevorturk-eldorado-a37d0c71e928f605d111d5f48b5786ff613bf676.tar.gz
tar -zxvf trevorturk-eldorado-a37d0c71e928f605d111d5f48b5786ff613bf676.tar.gz

Now, get all of those files out of that big, ugly directory and into the current working directory and ditch those old files:

toconnell@lana:~/example.com$ mv trevorturk-eldorado-a37d0c71e928f605d111d5f48b5786ff613bf676/* .
toconnell@lana:~/example.com$ rm -rf trevorturk-eldorado-a37d0c71e928f605d111d5f48b5786ff613bf676*

Now, follow the instructions in the README and copy the example yml files to the places where the application will look for real, non-example files:

toconnell@lana:~/example.com$ cp config/database.example.yml config/database.yml
toconnell@lana:~/example.com$ cp config/config.example.yml config/config.yml

Now, use your favorite editor to edit the last stanza in config/config.yml so that it matches the information of your site:

production:
  session_key: example_production
  session_secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  # Replace these X's and make this string (at least) 32 random alpha-numerics for good site security
  domain: http://example.com
  mailer: noreply@example.com  

NB: There are "dev" and "test" entries in this default file. If you're not planning on doing anything development related with this installation, you can safely delete those entries.

Once you've edited that file, that's it, so far as the non-git installation is concerned. To get El Dorado up and running, you'll need to do some minor database tasks. Those are covered in the next section.

5. Configure the Database

Since MySQL is deprecated, I'll be using PostgreSQL for the remainder of these instructions.

If you look at config/database.yml, you'll notice that it's essentially a blank template:

development:
  adapter: sqlite3
  database: db/development.sqlite3
  timeout: 5000
  # adapter: mysql
  # database: eldorado_development
  # username:
  # password:
  # host: localhost

test:
  adapter: sqlite3
  database: db/test.sqlite3
  timeout: 5000

production:
  adapter:
  database:
  username:
  password:
  host:

First, edit that file:

production:
  adapter: postgresql
  database: example
  username: example
  password: XXXXXXXXXXXXXXXXXXXX
  host: localhost

NB: Again: once you've added your "production" entries to this file, you can feel free to delete the "test" and "dev" lines, as they do nothing and could cause confusion down the line.

Now, create the database and the user:

toconnell@lana:~/example.com$ sudo su postgres -c "createuser example"
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) n
Shall the new role be allowed to create more new roles? (y/n) n
toconnell@lana:~/example.com$ sudo su postgres -c "createdb example"

Next, start the postgres monitor as the postgres user and make the a few changes:

toconnell@lana:~/example.com$ sudo su postgres -c psql
Welcome to psql 8.3.7, the PostgreSQL interactive terminal.

postgres=# ALTER USER example PASSWORD 'XXXXXXXXXXXXXXXXXXXX';
ALTER ROLE
postgres=# ALTER DATABASE example OWNER TO example;
ALTER DATABASE

Now, if you've got your Postgres database configured correctly and your new user can access your new postgres database, you're ready to rake the El Dorado production database:

toconnell@lana:~/example.com$ /opt/ruby-enterprise-1.8.6-20090610/bin/rake rake db:schema:load RAILS_ENV=production

Once the database is successfully raked, all you've got to do to finish up is configure Apache.

6. Apache Configuration

The following assumes that you're doing apache the "Debian way".

If this is true, the first thing you'll do is create a symlink in /var/www/ that points at your install directory:

lana:/var/www# ln -s /home/toconnell/example.com/

Next, create a file in /etc/apache2/sites-available with the name of your site and then create a symlink to it in /etc/apache2/sites-enabled.

The file should look something like this:

#
# example.com
#
 
<VirtualHost *:80>
  ServerName example.com
  ServerAlias www.example.com
  ServerAdmin youremail@example.com
  DocumentRoot /home/toconnell/example.com/public
 
  <Directory "/var/www/example.com">
    Options FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
  </Directory>
 
  RewriteEngine On
 
  RewriteCond %{HTTP_HOST} ^www\.example\.com$ [NC]
  RewriteRule ^(.*)$ http://example.com$1 [R=301,L]
 
  RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
  RewriteCond %{SCRIPT_FILENAME} !maintenance.html
  RewriteRule ^.*$ /system/maintenance.html [L]
 
  ErrorLog /var/log/apache2/example_error_log
  CustomLog /var/log/apache2/example_access_log combined
  RewriteLog /var/log/apache2/example_rewrite_log
  RewriteLogLevel 9
 
</VirtualHost>

NB: I've added some apache custom logging. Logs are good.

Once you've got the file in /etc/apache2/sites-available and the symlink in /etc/apache2/sites-enabled that points at that file, you should be ready to restart apache and get rolling:

lana:/etc/logrotate.d# /etc/init.d/apache2 reload

And that, as they say, is that. Once you reload apache, provided that your DNS is set up correctly and you haven't got any system problems beyond the scope of this document, your single instance of El Dorado should be ready for prime time.

Navigate to your site in your browser and create an administrative account: the first user who attempts to login will be the administrator. Once you've got your admin created, you're ready to start tweaking your new El Dorado site's appearance and adding users.

A note on upgrades: if you find you need/want to upgrade an instance of El Dorado that has been installed thus, consult the README. The basic gist is that you're going to want to download/copy the new source/program files over the old ones (while being careful not to erase your user-uploaded files) and then run rake db:migrate RAILS_ENV=production.