Installing Typo: MySQL, Apache, lighttpd and FastCGI
From Dev411: The Code Wiki
This is a step-by-step guide to installing Typo, a Rails-based blog engine. For now this page covers a fresh 2.6.0 install with the bundled Rails 1.0 for compatibility. This has been tested with Typo 4.0.0 r1188/Rails 1.1.4 (using SVN) and Typo 2.6.0/Rails 1.0. Additional software includes: Ruby 1.8.4, MySQL 4.1.x, Apache 2.x and lighttpd 1.4.x. The install was done on CentOS 4.2, a Red Hat rebuild, but this guide should be distro agnostic. It assumes that MySQL, Apache and lighttpd are already installed and operational. Entries on install specifics are available in the Apache (http://www.dev411.com/wiki/Category:Apache) and lighttpd (http://www.dev411.com/wiki/Category:Lighttpd) categories.
| Table of contents |
|
|
Requirements
Required: The following are necessary to get a test system up and running with the included WEBrick server.
- Ruby: 1.8.2 or higher; 1.8.4 or higher if using MySQL/Ruby drivers
- Rails: Since 2.6.0 Typo includes it's own version of Rails to take care of incompatibilities. Typo 4.0.0 comes with Rails 1.1.4 and Typo 2.6.0 comes with 1.0.0. Typoe 2.6.0 can also be used with Rails 0.13.1 or 0.14.0
- Database: MySQL 4.1.15/5.0.16, PostgreSQL and SQLite
- Ruby DB Drivers: MySQL/Ruby (http://www.tmtm.org/en/mysql/ruby/), etc.
Optional: Although the items listed here are optional, you'll really want them for a production system.
- FastCGI: 2.4.0 (http://www.fastcgi.com)
- Ruby FCGI library: ruby-fcgi (http://sugi.nemui.org/prod/ruby-fcgi/)
- Recommended web server: Apache, lighttpd or Litespeed. Apache 2.x and lighttpd 1.4.x are covered for now. Litespeed may be covered later.
Installation
This section covers installation of Typo to a working install with the built-in WEBrick test server. The following Post-Install section covers getting Typo working with a production webserver and other customizations.
Unpack Typo Distribution
There are a variety of ways to get Typo including a gem install, tarball and svn. In all cases you will end up with a directory structure including log and public directories. Only the public directory needs to be accessible under public_html directory so may want to put the distribution outside your public_html and simply alias Typo's public directory.
Tarball
Unpack tgz or zip in some directory: this is your deployment directory not a temporary install location. You can get the tarball distribution from RubyForge (http://rubyforge.org/frs/?group_id=555).
SVN
To stay up to date on the latest changes, install Typo from SVN. I like to get the revision number first and then create a directory associated with that revision number:
$ svn info svn://typosphere.org/typo/trunk $ svn checkout svn://typosphere.org/typo/trunk typo_r1188
Database Configuration
MySQL is currently covered.
MySQL
MySQL/Ruby Driver
You'll need the MySQL/Ruby driver if you don't already have it. It is available at the MySQL/Ruby page (http://www.tmtm.org/en/mysql/ruby/). Install instructions are at that page and also included in the tarball. The quick install method is as follows:
$ ruby extconf.rb $ make $ ruby ./test.rb $hostname $user $passwd $dbname # make install
Create Database
The first thing to do is create a database. Login as a root user and create/grant permissions to a user to create the database. Typo 2.6.0 does not let you prefix the tablenames with a custom prefix so it's safer to just create a new database for Typo. The following simply grants 'all' capabilities to the user. In practice, you'll want something more restrictive.
$ mysql -h localhost -u root -p Enter password: ******** mysql> grant all on mytypodb.* to username@localhost identified by 'password'; mysql> quit
If you already have a user, simply grant permissions.
mysql> grant all on mytypodb.* to username@localhost;
Login as the mysql user and create the database:
$ mysql -h localhost -u username -p Enter password: password mysql> create database mytypodb; Query OK, 1 row affected (0.01 sec) mysql> quit
Once the database is created, simply load the sql file.
$ mysql mytypodb -h localhost -u username -p < db/schema.mysql.sql
database.yml
Edit the config/database.yml and set your hostname, user, passwd and dbname. This file is self-explanatory and very straight-forward.
Database migration with rake
If you are upgrading an existing system, use rake (http://rake.rubyforge.org/) to migrate your database. An easy way to install rake is to use Ruby Gems:
gem install --remote rake
With your database.yml file set up, you can update your development environment by changing your working directory to the typo base directory and then typing:
$ rake migrate
To update your production environment, use:
$ rake migrate RAILS_ENV=production
Running on WEBrick
Start the test server and continue the install process via the web browser. This uses WEBrick.
$ script/server -e production
Point your web browser to http://your.domain:3000 and continue the install process.
Post-Install
This section covers integrating Typo with a production web server, FastCGI and customization via themes.
Web Server Integration
Shebang line
Typo scripts come with the following shebang line:
#!/usr/bin/env ruby
This can cause a problem because ruby is typically installed in /usr/local/bin which is often not in the path for the webserver user. To get around this, either add it to the path or change the shebang line in the relevant files. If you prefer to change the files, edit the following files:
- public/dispatch.cgi
- public/dispatch.fcgi
- public.dispatch.rb
and change the shebang line to:
#!/usr/local/bin/ruby
File System Permissions
The webserver user will need write permissions on the typo log directory including all contents. Typo will also work better if public directory and contents are writable. It will ask for 666 permissions on log/production.log and attempt to create a log/fastcgi.crash.log file.
FastCGI
Get the FastCGI distribution from FastCGI.com (http://www.fastcgi.com)'s distribution directory http://www.fastcgi.com/dist/ which also has mod_fastcgi for Apache.
$ ./configure $ make # make install
This will install the fcgi libraries in /usr/local/lib which are required by ruby-fcgi.
ruby-fcgi
To use FastCGI with Ruby, you'll need ruby-fcgi which is available at http://sugi.nemui.org/prod/ruby-fcgi/. The install is simple as long as your fcgi libraries are in the default place. The README covers explicit include directories.
$ ruby install.rb config $ ruby install.rb setup # ruby install.rb install
Apache
Apache can work with FastCGI using mod_fastcgi, mod_fcgid or external FastCGI servers. For now, only the first two are discussed.
mod_fastcgi
mod_fastcgi is the traditional way to use FastCGI with Apache and available at http://www.fastcgi.com/dist/. The instructions below are for Apache2. For Apache 1.x, see the INSTALL file.
$ cd <mod_fastcgi_dir> $ cp Makefile.AP2 Makefile $ make # make install
This assumes Apache2 is installed at /usr/local/apache2. To change the installation directory use:
$ make top_dir=/opt/httpd/2.0.40
Next, Apache needs to be configured to use FastCGI which can be used in static, dynamic or external mode. Scott Laird describes these modes (http://scottstuff.net/blog/articles/2005/07/20/apache-tuning-for-rails-and-fastcgi) as:
- Static. FastCGI servers are started when Apache is reloaded and remain running.
- Dynamic. FastCGI server processes are started whenever a FastCGI URL is hit. Excess processes are killed off when there’s no traffic.
- External. Apache and your FastCGI app talk via TCP sockets.
LoadModule fastcgi_module modules/mod_fastcgi.so
<IfModule mod_fastcgi.c>
AddHandler fastcgi-script .fcgi
FastCgiIpcDir /tmp/fcg_ipc
FastCgiServer /var/www/html/typo/public/dispatch.fcgi \
-idle-timeout 120 -initial-env RAILS_ENV=production \
-processes 2
</IfModule>
This is discussed in the Deployment and Scaling chapter of the Agile Web Development with Rails book.
mod_fcgid
mod_fcgid is a binary-compatible alternative to mod_fastcgi availabe at http://fastcgi.coremail.cn/. Some capabilities include:
- Strict control on process spawn
- Simple spawning-speed control strategy
- Fastcgi server error detection
If you're running Apache2, you'll also want the Fcgid Apache2 patch (http://constant.northnitch.com/~chip/mod_fcgid.1.07-apache2.2.0.patch). In case the link doesn't work in the future, the patch is:
Index: arch/unix/fcgid_proc_unix.c =================================================================== --- arch/unix/fcgid_proc_unix.c.orig +++ arch/unix/fcgid_proc_unix.c @@ -4,6 +4,7 @@ #include <netinet/tcp.h> /* For TCP_NODELAY */ #define CORE_PRIVATE #include "httpd.h" +#include "mpm_common.h" #include "apr_thread_proc.h" #include "apr_strings.h" #include "apr_portable.h"
The notes below are adapted from FolkWolf's Typo installation notes (http://folkwolf.net/blog/pages/installation).
$ wget http://fastcgi.coremail.cn/mod_fcgid.1.07.tar.gz $ tar -xvzf mod_fcgid.1.07.tar.gz $ cd mod_fcgid.1.07 $ wget http://constant.northnitch.com/~chip/mod_fcgid.1.07-apache2.2.0.patch $ patch -p0 < mod_fcgid.1.07-apache2.2.0.patch $ make # make install
Edit httpd.conf as follows:
LoadModule fcgid_module modules/mod_fcgid.so
<IfModule mod_fcgid.c>
AddHandler fcgid-script .fcgi
IPCCommTimeout 40
IPCConnectTimeout 10
DefaultInitEnv RAILS_ENV production
SocketPath /tmp/fcgidsock
</IfModule>
Also edit the public/.htaccess file and change fastcgi-script to fcgid-script as follows:
# General Apache options AddHandler fcgid-script .fcgi # AddHandler fastcgi-script .fcgi
External FastCGI Server
It is also possible to run FastCGI as an external stand-alone server with some applications. This isn't covered at this time.
httpd.conf revisited
The previous sectons on mod_fastcgi and mod_fcgid cover cover some editing of httpd.conf. This section provides the VirtualHost section for enabling Typo. The following attaches Typo to the /blog location. This is adapted from FolkWolf's Typo installation notes (http://folkwolf.net/blog/pages/installation).
<VirtualHost *:80>
#The following 4 lines are specific to your site
#don't use these lines
ServerAdmin you@your.domain.com
DocumentRoot /var/www/html
ServerName your.domain.com
ServerAlias domain.com
#The following two lines redirect a bare hostname
#to the /blog Alias we'll setup later on in the file
redirectMatch ^/$ http://your.domain.com/blog/
redirectMatch ^$ http://your.domain.com/blog/
#Alias the /blog to the real dir
Alias /blog /path/to/typo/public/
<Directory /path/to/typo/public>
Options All ExecCGI
AllowOverride All
Order allow,deny
Allow from all
RewriteBase /blog
</Directory>
<Location /blog>
RewriteEngine On
# Let apache handle purely static files like
# images by itself.
RewriteCond %{REQUEST_FILENAME} !-f
# Send Everything else to Typo
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]
</Location>
</VirtualHost>
lighttpd
See Installing lighttpd and FastCGI for Catalyst to get a base lighttpd+FastCGI installation installed and working.
lighttpd.conf
The following is a representative lighttpd.conf file for a static FastCGI configuration. For external FastCGI servers see Configuring FastCGI for lighttpd and Catalyst (http://www.dev411.com/wiki/Installing_lighttpd_and_FastCGI_for_Catalyst#Configuring_FastCGI) which covers external server connections via sockets and TCP.
$HTTP["host"] =~ "^(your.)?domain.com" {
server.document-root = "/path/to/typo/public/"
server.error-handler-404 = "/dispatch.fcgi"
server.indexfiles = ("dispatch.fcgi")
server.errorlog = "/usr/local/lighttpd/logs/lighttpd_error.log"
url.rewrite = ( "^/$" => "index.html", "^([^.]+)$" => "$1.html" )
fastcgi.server = (
".fcgi" => (
"localhost" => (
"socket" => "/tmp/lighttpd-typo-fcgi.socket",
"bin-path" => "/path/to/typo/public/dispatch.fcgi",
"bin-environment" => ( "RAILS_ENV" => "production" ),
"max-load-per-proc" => 25,
"min-procs" => 1,
"max-procs" => 1,
"idle-timeout" => 60,
)
)
)
}
User and Group
Just something to be aware of but sometimes the lighttpd user and the fastcgi user will be different. The webserver user will need permissions on the log directory and the fastcgi user will need permissions on the public directories. It may be easier just to make them the same user.
Changing the Root URL
By default, lighttpd and Rails will run Typo at /. To install Typo somewhere else, add the following to config/environment.rb:
ActionController::AbstractRequest.relative_url_root = "/blog"
A side-effect of this is that Rails will add /blog to all the static files as well so /javascripts/typo.js becomes /blog/javascripts/typo.js. Lighttpd, however, doesn't know about the relative_url_root so it will return a 404. To fix this, just link the public directory to the mount point, /blog in this case:
$ cd /path/to/typo/public $ ln -s . blog
Typo Customization
Themes
Azure by Justin Palmer is the default theme that ships with Typo. If you are interested in different look, TypoGarden (http://www.typogarden.org/) has a number of themes.
Available Themes
A while back Typo Garden ran a theme contest (http://www.typogarden.org/articles/2005/12/10/final-results) where over 120 themes were submitted. The Typo Theme Viewer (http://www.dev411.com/typo/themes/) provides an easy way to preview the themes. This currently only covers 117 of the themes since some don't have posted screenshots and thumbnails.
The highest rated themes are:
- Origami (http://typogarden.com/articles/2005/11/29/origami-theme)
- Phokus (http://typogarden.com/articles/2005/11/29/phokus-theme)
- Laughing at You (http://typogarden.com/articles/2005/10/24/laughing-at-you-theme)
- Royal Vinter (http://typogarden.com/articles/2005/11/29/royal-vinter-theme)
- I am Rice (http://typogarden.com/articles/2005/11/16/iamrice-theme)
- Bird Flu (http://typogarden.com/articles/2005/11/09/bird-flu-theme)
- Modernist (http://typogarden.com/articles/2005/11/16/modernist-theme)
- Lush (http://typogarden.com/articles/2005/11/28/lush-theme)
- Inkling (http://typogarden.com/articles/2005/11/29/inkling-theme)
Theme Installation
To install a theme, unzip the file into the top level theme directory and then go to Themes in the Admin console to activate it. Your fastcgi user will need permissions on the public directory to make the necessary changes.
Since the contest, Typo has changed causing a number of themes to break. Piers Cawley (http://www.bofh.org.uk/articles/2006/04/09/scratching-an-itch) has an article on this. One common problem is rendering sidebars. Look for the following in layouts/default.rhtml:
<%= render_component(:controller => 'sidebars/sidebar', :action => 'display_plugins') %>
and change it to:
<%= render_sidebars %>
URIs
Some of the URIs are easily changed by editing the config/routes.rb file. The two changes here have been implemented on the Dev411 Blog (http://www.dev411.com/blog/).
Articles
By default, Typo adds articles to the path for blog entries, however, it's often nice to remove that and just go directly to the year or page. To do this edit the config/routes.rb file and remove articles where relevant.
Category to Tag
By default, Typo uses the category path for categories. If you would like to change this to something else, say tag, edit the following two lines:
#map.connect 'category/:id', map.connect 'tag/:id',
#map.connect 'category/:id/page/:page', map.connect 'tag/:id/page/:page',
Also edit the plugin file omponents/plugins/sidebars/category/content.rhtml and change the <h3> innerHTML to Tags from Categories.
Page Title
In Typo 2.6.0, the individual article pages only have the article title in the page however it may be nice to have the name of the blog in the page as well. This can be added by editing app/controllers/articles_controller.rb and make the following change:
# old line: # @page_title = @article.title # new line: @page_title = @article.title + ' - ' + config[:blog_name]
In 2.6.0 this line appears in the read and permalink methods.
Feedburner
If you wish your feeds to go through Feedburner there are two files you need to edit:
themes/<your_theme>/layouts/default.rhtml
components/components/plugins/sidebars/xml/content.rhtml
Note that as of Typo 4.0, you will get context specfic feeds on category and tag pages. Feedburner does not seem to handle sub-feeds so if you want these go through Feedburner you'll either need to set them to the main feed used by Feedburner or create a Feedburner feed for every category and tag you use.
Additional Information
Admin URI
Admin interface is at /admin from where ever you're running Typo, e.g. http://your.domain.com:3000/admin, http://your.domain.com/blog/admin.
Client Setup
If you are using desktop client (http://www.typosphere.org/trac/wiki/DesktopClients), set client to Movable Type API and enter http://your.domain.com/backend/xmlrpc as endpoint address.
Further Reading
- Blog entries on Typo (http://www.dev411.com/blog/tag/typo)
Related Entries
External Links
- Planet Typo (http://planettypo.com/)
- Typo Forums (http://typoforums.org/)
- Typo Garden (http://typogarden.org/)
- FolkWolf's Apache2 FCGID Integration (http://folkwolf.net/blog/pages/installation)
- Hans Fugal's Typo install notes (http://hans.fugal.net/typo/articles/2006/04/01/typo)
- Scott Laird's Apache Tuning for Rails and FastCGI (http://scottstuff.net/blog/articles/2005/07/20/apache-tuning-for-rails-and-fastcgi)
