I'm pleased to announce that El Dorado is now compatible with Heroku, the instant Ruby platform.
This means that deploying El Dorado is no longer a pain in the ass. It also means that you can get started with El Dorado for free. Just follow along with the installation and deployment instructions in the README and you're good to go.
If you need help along the way, drop by the support site: http://eldorado.heroku.com/
Enjoy!
I don't really care for the suggested approach in the Heroku docs for setting configuration variables locally. I have an open-source project that I'm working to get onto Heroku, so I decided to do a little work to come up with a solution that I prefer. I think this would work well for open source projects, as well as projects with multiple developers.
Here's the basic idea:
You have a config file that contains all of your local configuration variables. It looks a lot like database.yml.
# config/config.yml development: session_key: example_development session_secret: ESl6X3oKM1i1RRrD2QLwUUzz9jr1zxNO domain: http://example.com test: session_key: example_test session_secret: vrwPpJTvwnMVLP1wTSgqigSl7PMI7QcE domain: http://example.com production: session_key: # any string identifying your app session_secret: # a random, secret string at least 32 characters long domain: # http://example.com mailer: # noreply@example.com
You perform a little trickery in environment.rb to prefer the Heroku ENV storage of config vars (in the production environment), but you fall back to your config.yml if the config vars aren't found in ENV (in the development and test environments).
# config/environment.rb Rails::Initializer.run do |config| require 'yaml' # support yaml and heroku config vars, preferring ENV for heroku CONFIG = (YAML.load_file('config/config.yml')[RAILS_ENV] rescue {}).merge(ENV) config.action_controller.session = { :key => CONFIG['session_key'], :secret => CONFIG['session_secret'] } end
Then, you create a rake task (rake heroku:config) that can be used to send all of the config vars for your production environment up to Heroku. This task can be invoked once to set things up, but can also be run again if you need to make any additions or changes.
# lib/tasks/heroku.rake namespace :heroku do task :config do puts "Reading config/config.yml and sending config vars to Heroku..." CONFIG = YAML.load_file('config/config.yml')['production'] rescue {} command = "heroku config:add" CONFIG.each {|key, val| command << " #{key}=#{val} " if val } system command end end
This way, you've got all of your config vars stored with the project (.gitignored, of course)...
# .gitignore
/tmp/**/*
/log/*
*.log
/tmp/restart.txt
/config/config.yml
/config/database.yml
/db/*.sqlite3
...and you can easily set what you need on Heroku, like so:
$ rake heroku:config
Reading config/config.yml and sending config vars to Heroku...
Adding config vars:
session_key => example_production
session_secret => 1WlkMkYYi5611vtF...0ZMS2G3Xl67s4lEIK4sj65
domain => http://example.com
mailer => noreply@example.com
Restarting app...done.
The result is a pretty nice, I think.
You can see the installation and deployment instructions for my open source project El Dorado if you're curious about the overall flow.
I'd love to get some feedback on this approach, but I really like it so far :)
These instructions require and assume the following:
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.
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.
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.
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.
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.
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.
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.
I'm pleased to announce the release of El Dorado version 0.9.2 - the "group chat" edition. You can download it right away, or check out the demo, testing, and support site here:
Since we last spoke at the end of January, there's been a goodly amount of activity with El Dorado. The highlight, of course, is the new group chat feature:
This is a very simple and lightweight implementation that's perfect for small groups. It works solely with the tools provided by Rails and doesn't add anything to the overall requirements for running El Dorado. I've been using it with my group of friends for a few weeks now, and it's been working great. I'm sure that I'll have some more features to announce with the next release, but my favorite little touch so far is the "who's in the chat room and when was the chat last active" indicator on the home page:
In addition to the addition of group chat, there have been a number of improvements to other parts of the app and quite a bit of back-end optimization/refactoring. Here's a quick list of the new features:
Of course, you can follow along with all of the activity in El Dorado on the commit log at github. You see, being the lemming that I am, I've followed Rails to github and Lighthouse already. I haven't had time to settle into Lighthouse just yet, but I've been having a blast with git and github.
In fact, I gave a presentation at Chicago Ruby and spent a fair amount of time talking about making the move to git. Definitely flip through the PDF to learn all about the origin of El Dorado (where the name came from, etc) but take my word for it about one thing: git/github is the way to go:
If you believe the PDF, then the upcoming of releases should go something like this:
Thanks to git/github, jxl has been working on a localized version of El Dorado using Gibberish, and he's already completed a Dutch translation. I'll be working with him to pull his changes into my repo for the next release. If you're interested in translating El Dorado into another language, please do get in touch!
I think that about covers it... so... Welcome to El Dorado v.0.9.2!
Learn more and/or download El Dorado here: http://almosteffortless.com/eldorado/
I'm pleased to announce the first public release of El Dorado: a full-stack community web application written in Ruby/Rails. This is a stable beta version of the app, which is being released in anticipation of the 1.0 release scheduled for this spring.
The app features a forum, community event calendar, shared file storage, and a randomized header image gallery. The forum is somewhat modeled on PunBB (one of the more popular PHP forums) and can import from an existing site using PunBB.
The app has been used in production since late July '07. The setup/administration process still leave something to be desired, but the end-user functionality is quite well tested.
You can get the download or more information on the El Dorado homepage, or check out the demo, testing, and support site here: eldorado.heroku.com. Also, consider subscribing to the almost effortless RSS feed to stay informed about upcoming releases and the occasional Ruby/Rails-related post.
Enjoy!
