- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
