Typo installer

As I mentioned in the Typo 4.0.0 announcement, Typo now includes a .gem-based installer that makes it easy to install Typo. Just install the Typo gem (gem install typo) and run the Typo installer (typo install /some/path) to create a new Typo blog in /some/path. The installer will install all of Typo’s files, create a working set of config files, create a SQLite database for you, and start the Mongrel web server on a random TCP port. It’ll also create a set of sample Apache and Lighttpd configuration files to show you how to tie Typo into your existing web server. One warning: this will only work right if you already have SQLite 3 and SWIG installed on your system. If they’re missing, then you’ll get weird warnings and errors. SWIG is particularly strange–if it’s missing, then you’ll get sporadic test failures when trying to use SQLite.

The same installer can also be used for upgrades–if you’ve installed one of the Typo 3.99.x pre-releases, then you can upgrade the same way you installed Typo in the first place–run gem install typo to grab a newer Typo gem, and then typo install /some/path to upgrade. Typo will recognize the existing install, back up the database, shut down the existing Mongrel server, install new files, upgrade the database, and restart Mongrel.

Once Typo is installed you can test it by connecting directly to Mongrel with your web browser; the installer will display the URL for you. Normally, for production use, you’d configure some sort of proxy or load balancer (like Apache’s mod_proxy) in front of Mongrel, so users talk to Apache and Apache talks to Mongrel. The installer creates a number of example configs in the installer/ directory. Once thing to be careful about–you’ll need to make sure that Mongrel and Typo are restarted when your web server reboots. You can start them by running typo start /some/path. You’ll need to talk to your system administrator or hosting provider to learn the best way to start Typo on boot.

Compared to the half-dozen mutually contradictory install guides that existed before, this is a big step forward. However, not everyone wants to (or can) run Typo under Mongrel with SQLite. Some hosting environments make HTTP proxying difficult, while others would rather use a “real” database. So, in the Rails spirt of convention over configuration, I built the installer to use Mongrel and SQLite by default, but you can configure it for your favorite database with a bit of extra work. There are a number of configuration settings that control the installer’s behavior. The typo config /some/path command will show existing variables. You can change them via typo config /some/path var=value.

As of Typo 4.0.0, the installer knows about 6 different configuration variables:

  • web-server: which web server technology Typo will use. It defaults to mongrel. Other options are mongrel_cluster and external. If you want to use FastCGI, then set web-server to external.
  • threads: if web-server is set to mongrel_cluster, then threads controls how many Mongrel back ends are used.
  • port-number: which TCP port Mongrel listens on. This defaults to a random number between 4000 and 5000. The mongrel_cluster server uses one TCP port per thread, starting with port-number and counting up.
  • url-prefix: if Mongrel or higher is installed, then url-prefix can be used to move Typo into a subdirectory. If you want to run Typo on http://www.example.com/blog, then you’ll need to set url-prefix to /blog.
  • bind-address: which IP address Mongrel binds to.
  • database: which database server Typo will use. The default is sqlite. If you change this, then the installer won’t create a SQLite database for Typo or try to back the SQLite database up during upgrades.

So, if you want to use the Typo installer with FastCGI and Mysql, then you’ll want to do this:

  $ typo config /some/path web-server=external database=mysql

You’ll also need to edit database.yml and create your own database. There are schema files in db/schema.*.sql for several different databases. Pick the one that matches your database.

The typo command supports 7 sub-commands:

  • install [version] [config=value ...]. Installs or upgrades Typo. You can optionally specify which version to install, if you have multiple Typo .gems installed. You can also use the installer to install directly out of a Subversion checkout by specifying version cwd and running typo from inside of the Subversion directory.
  • start. Starts the Mongrel or mongrel_cluster webserver. If Mongrel has been disabled via web-server=external, then this command does nothing.
  • run. Just like starts, but runs Mongrel in the foreground when possible.
  • stop. Stops Mongrel. Like start, it is ignored if Mongrel has been disabled.
  • restart. Stops and restarts Mongrel.
  • config [name=[value] ...]. Without parameters, it shows Typo’s current configuration. With parameters, it sets the configuration parameters. If you specify name= without a value, then it clears the variable.
  • sweep_cache. Sweeps Typo’s cache. This can be useful for troubleshooting.

That should be all that you need to know to install Typo and keep it running. Any questions?

Posted by Scott Laird Sun, 23 Jul 2006 23:09:56 GMT


  1. thechak 1 day later:

    Upgrading from Typo 2.6.0_with-rails release (using Postgres), I get:

     Migrating Typo's database to newest release
    rake aborted!
    Multiple migrations have the version number 1
    (See full trace by running task with --trace)
    /opt/local/lib/ruby/gems/1.8/gems/typo-4.0.0/./installer/rails-installer.rb:386:in `migrate': Migration failed (RailsInstaller::InstallFailed)
            from /opt/local/lib/ruby/gems/1.8/gems/typo-4.0.0/./installer/rails-installer.rb:520:in `in_directory'
            from /opt/local/lib/ruby/gems/1.8/gems/typo-4.0.0/./installer/rails-installer.rb:384:in `migrate'
            from /opt/local/lib/ruby/gems/1.8/gems/typo-4.0.0/./installer/rails-installer.rb:86:in `install_sequence'
            from /opt/local/lib/ruby/gems/1.8/gems/typo-4.0.0/./installer/rails-installer.rb:61:in `install'

    The command I ran was:

    typo install typo4 database=postgres

  2. thechak 1 day later:

    I suppose it’s worth mentioning that the database= option causes the installer to cp a file called “installer-path/config/database.yml.#{database_name}”

    The available files in that directory are:

    • database.yml-pgsql
    • database.yml.sqlite

    Note that the pgsql file uses a dash instead of a period, so postgres users are SOL.

     Creating default database configuration file
    /opt/local/lib/ruby/1.8/fileutils.rb:1182:in `stat': No such file or directory - /Users/chak/web/typo4/config/database.yml.pgsql (Errno::ENOENT)

    Also, there doesn’t appear to be a mysql file, though I didn’t try testing with database=mysql.

  3. Erik 8 days later:

    I get this error as well. Any progress in finding out how to solve it?

    Haven’t read enough about migrations to know why this occurs myself…

  4. Scott Laird 9 days later:

    I’m going to release 4.0.1 next week, when I get back from vacation. It should work much better with slightly weird environments :-).

  5. pfig about 1 month later:

    i’m on 4.0.3 and still get the “multiple migrations…” error (also migrating from a 2.6.0_withrails). my database is on mysql.

  6. eitan about 1 month later:

    why aren’t 2.6 -> 4.0 upgrade instructions posted directly on the typo web site?

  7. samio 4 months later:


  8. grimm@grimmwerks.com 5 months later:

    Hey Scott - I’m trying to get typo up and running on a mac osx using mysql and the built in apache. I’ve followed your directions (and also tried following 7http://blog.aidenbordner.com/articles/2006/07/24/getting-typo-4-0-0-running-on-dreamhost but more for my mac).

    Whenever I try to connect with the regular port I just get file listings; but when I connect via the port thrown at me (ie 4282 in my case) it seems to be working.

    What dopey thing have I done?

  9. leon 5 months later:

    o ka delte jaz nič ka vi ????????