Tech Stuff - Ruby - Typo

Typo is blogging system implemented using the Ruby on Rails framework. This page is devoted to installing, testing and running Typo on FreeBSD with a production target of Apache 1.3.

These notes will use mongrel with a non-standard port number for testing Typo without breaking the Apache production service but then move it to a production Apache webserver environment. There are also multiple other web server configurations possible.

Rails is very fast moving environment constantly pushing the ruby envelope. Before you do anthying - make sure your ruby installation is the very latest - you will get warning messages if it's not as well as wasting your time with any number of inexplicable problems. If you are using portupgrade you are already using ruby whether you realized it or not. If you are not sure whether ruby is installed or not do the following:

# from a command line issue
ruby -v
# command not found = no ruby, else version will be displayed

# or 
pkg_info|grep ruby
# check for ruby-x.x.x

Update your ports collection with a ports-all parameter or portsnap.

To upgrade or install ruby:

# assuming portupgrade is installed
portupgrade ruby-x.x.x

# or if portupgrade is not installed then installing 
# it will also install the latest version of ruby
cd /usr/ports/ports-mgmt/portupgrade
make install clean

# or no portugrade or ruby
cd /usr/ports/lang/ruby18

Install Typo Components

Typo is available as a port or it can be installed as a Gem.

If you install typo via ports (www/typo) it does a full rails install (its dependency is www/rubygem-rails) so you can subsequently install rails frameworks with no further action. However the port does NOT make available the typo install commands which greatly simplify the typo installation. Instead you will need to use the manual process described here which looks deceptively simple but if anything goes wrong may require significant de-bug effort.

Note: We had hoped that installing www/rubygem-rails-app-installer would fix the typo command problem but it did not in our case. As a final point the typo port assumes the default typo mode and installs swig and sqlite.

If this is your first rails install, you are using anothr database (mysql, postgres are supported) and especially if you are new to ruby and want minimal risk we (reluctantly) recommend this route (assuming ruby is installed):

# install rubygems
/usr/ports/devel/ruby-gems
make install clean

# OR
postinstall -PR ruby-gems

# install rails from ports
cd /usr/ports/www/rubygem-rails
make install clean

# or 
portinstall -PR rubygem-rails

# install typo via gems
gem install typo

This install process makes certain that the typo commands used later are available. Plenty of time later to learn the rails stuff rather than fighting it out-of-the-box.

One of the happy side effects of this method is that you can do multiple typo installs if this is required whereas with the ports install you would need to copy the directory and hack the configuration files again.

The downside is that typo will not appear in your package collection (using pkg_info) but can only be verified using gems (gem list) and if you are using the default configuration you will need to manually install swig (devel/swig and devel/swigruby) and sqlite (databases/sqlite3). There is not winning strategy.

Typo Install Commands

If the typo package is installed using the gems process then the typo command is installed in /usr/local/bin/typo). The basic install command format is:

# directory must exist
mkdir /path/to/blog/dir
# if you are going to use this directory under apache
# then make sure it is within the ServerRoot

typo install /path/to/blog/dir [options]

If no options are provided the default install will assume sqlite. but this can be overriden by numerous options. If the mysql or postgres installation is new then default commands can also be used. MySQL security.

Options Supported

database=mysql | postgres | sqlite [default sqlite]
db_user=db-user-name [default root]
db_password=db-user-password
db_name=db-name [default no password]
db_host=fqdn-db-host-name [default localhost]
port-number=xxxx [default random above 4000]
rails-environment=production | test | development [default production]
web-server=mongrel | external | webrick [default mongrel]

To install for an exiting mysql database using the default web server (mongrel) proceed as follows:

# create a mysql account for the typo user
# login to mysql as root and create special accounts
GRANT ALL PRIVILIGES on typo_db_name.* to 'typo_user'@'localhost' \
 IDENTIFIED BY 'typo_password' WITH GRANT OPTION;

# the installer also creates a test database
GRANT ALL PRIVILIGES on typo_db_name_test.* to 'typo_user'@'localhost' \
 IDENTIFIED BY 'typo_password' WITH GRANT OPTION;
# the above is not necessary but prevent error mesages on the install

# install typo command
typo install /path/to/blog/dir database=mysql db_user=typo_user \
 db_password=typo_password db_name=typo_db_name
# replace typo_user, typo_password and typo_db_name with your values

# the install process will also try and create a database called 
# typo_db_name_test - the failure will be displayed but is not fatal

The install process will create a database called typo_db_name_test (it appends _test to the given db_name= value) in the above example. The failure is displayed but is not fatal so can be ignored unless you want a separate test process. Unfortunately a further **** TESTS FAILED **** message with in most cases related to the _test database not being present.

The resulting system will run under the production environment and use mongrel. The command typo config /path/to/blog/dir will display the parameters being used (typo config /path/to/blog/dir will display the current configuration. The final part of the install will start mongrel and display the port number being used. To test your typo installation use a web browser:

# if the web brower is on the same machine
http://localhost:xxxx
# where xxxx is the port number output when 
# the install was run
# or it can be displayed (port-number) using
# typo config /path/to/blog/dir

# if the browser is on another machine then use
http://z.z.z.z:xxxx
# where z.z.z.z is the ip address of the machine
# and xxxx is the port number

# OR 
http://some-host-name:xxxx
# where some-host-name resolves to the ip address of the PC

Typo Directory Structure

/	The root of your directory.
app	Rails. The root of your directory.
bin	TYPO. The root of your directory.
components	The root of your directory.
config	Contains configuration information such as: routes.rb environment.rb - defines the basic initialization process of the application. Sets whether the application is in test, development or production. routes.rb - defines the way an application routes incoming requests. database.yml - defines the database type, name and access credentials. these may be unique for the three environments (test, development and production).
config/environments	Contains envionmental information about the three rails environments namely: production, test and development. The currently active environment is controlled by the envonmental variable RUBY_ENV which is set in environment.rb.
db	Typo. SQL import files for various databases.
db/backup	The root of your directory.
db/convertors	The root of your directory.
db/migrate	The root of your directory.
db/scripts	The root of your directory.
db/update	The root of your directory.
doc	documentation for application such as install notes.
installer	TYPO. The root of your directory.
lang	TYPO. The root of your directory.
lib	The root of your directory.
log	Contains log files for the application. The main logs refect the mode so that if you are running in development mode the log will be written to development.log. Additional logs may also be written here, such as crash logs.
public	The root directory for the application. When you application starts it will access a file in this directory. the deault file name is dispatch.fcgi, dispatch.cgi and dispatch.rb.
script	The root of your directory.
spec	TYPO. The root of your directory.
spec/controllers	TYPO. The root of your directory.
spec/fixtures	TYPO. The root of your directory.
spec/helpers	TYPO. The root of your directory.
spec/models	TYPO. The root of your directory.
test	The root of your directory.
themes	TYPO. The root of your directory.
tmp	The root of your directory.
vendor	The root of your directory.

Troubleshooting

During the initial installation of typo we had a lot of problems. Probably in spite of the efforts of the developers. In a number of cases we found the solutions on the web (many thanks to those folks whom we rudely did not take note of) in most cases we had to find a solution. In case they are useful here were the problems and their solutions.

Check the log

Rails does quite a bit of logging. The logs are maintained in the /path/to/blog/dir/log directory and the active log is defined by the production environment so if you are using a production environment (the rails_environment parameter in a typo config /path/to/blog/dir command) then the active log is production.log. The messages are all ruby format so you may as well get used to them now.

rake aborted! syntax error from the database.yml file

Having religously edited the /dir/db/database.yml file we them ran rake db:migrate and got this error:

rake aborted! syntax error from the database.yml file

After messing around we found that YAML is pretty picky and the offending line turned out to be the edited password line which should read:

# the offending line was this one
  password: user-password
# the space after the colon is vital
# there must be no cruft after user-password

Which let us move on the next error.

Admin woes

Having finally booted to the opening screen we decided that we would like to try a test post. OK, so just how do we do that. Seems that we have been living on the dark side of the moon for the last couple of years because everyone knows that you use blog.url/admin :

# assume the site is www.example.com (or example.com)
# and the blog is /blog (are we original or what)
# then the admin url is
www.example.com/blog/admin
# if you are running under webrick or 
# mongrel standalone in test mode 
# then it will look something like this
www.example.com:xxxx/admin

So once you figure that you may be presented with a login prompt rather that an auto sign-up screen and everything you try is doomed to failure. the solution here lies in the fact you installed the release database which contains live accounts. You only get the auto sign-in screen if there are no users in the database. Therein lies the secret. Using a MySQL (or whatever you database is) tool like phpmyadmin or our trivial mysql tools and delete ALL the entries in the users table. If you are using mysql directly the syntax is something like (see our mysql survival guide):

# LOG-in to mysql
USE your-typo-db-name;
SELECT id from users;
# displays all the ids in the file
DELETE FROM users WHERE is="x";
# where x is one of the id values
# repeat for all displayed ids
# until table is empty

When you refresh the admin URL in your browser you should now be presented with the auto sign-in screen.

Can't get to Admin or get a nilClass message

If everything goes to the same place and shows a nilClass message or nothing takes you to the admin screen then your database is in a unstable state. This will typically happen if you use the manual install and use rake db:migrate or something fails during early configuration. The following instructions only work if you have so far not added anything that you want to keep. List all the records in the triggers table and delete them ALL, then for good measure delete ALL sessions table records as well. Then refresh the view in your browser and it should display the home page of your blog - and /admin should work.

To manipulate your MySQL (or whatever you database is) use a tool like phpmyadmin or our trivial mysql tools and delete ALL the entries in the trigger table. If you are using mysql directly the syntax is something like (see our mysql survival guide):

# LOG-in to mysql
USE your-typo-db-name;
SELECT id from triggers;
# displays all the ids in the table
DELETE FROM users WHERE id="x";
# where x is one of the id values
# repeat for all displayed ids
# until table is empty

# to delete all session records
SELECT id from sessions;
# displays all the ids in the table
DELETE FROM users WHERE id="x";
# where x is one of the id values
# repeat for all displayed ids
# until table is empty

Can't get to Admin or get a nilClass message

# LOG-in to mysql
USE your-typo-db-name;
SELECT id from triggers;
# displays all the ids in the file
DELETE FROM users WHERE id="x";
# where x is one of the id values
# repeat for all displayed ids
# until table is empty

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.