Catalyst and local configuration files

This just took me two hours to debug, so I thought I’d go ahead and turn it in to a post…


Catalyst supports reading a config file. usually called myapp.conf.  You can also add extra configuration, but figuring out where it goes took me ages.

In a nutshell, Catalyst will read myapp.conf and myapp_local.conf.

You can change what the ‘local’ part in that is by setting an environment variable called MYAPP_CONFIG_LOCAL_SUFFIX or one called CATALYST_CONFIG_LOCAL_SUFFIX.

If MYAPP_CONFIG_LOCAL_SUFFIX is set, CATALYST_CONFIG_LOCAL_SUFFIX is apparently ignored.  (You don’t get two additional config files, just the one.)

MYAPP_CONFIG_LOCAL_SUFFIX applies only to MyApp, where CATALYST_CONFIG_LOCAL_SUFFIX will be applied to any Catalyst app.  Be careful with it.

A Note About MyApp

Let me pause for a moment!  This needs to be explained somewhere and I don’t remember seeing it. Catalyst often refers to “MyApp”.  This means the name of your catalyst application, as you created it and as it shows in your configuration.  Sometimes it is mixed case, sometimes it is all uppercase, and sometimes it is all lowercase.  When you see “MyApp” used it is talking about your own application, and you should use your application’s name instead of MyApp.  I can get that out of the way and get back to what I was talking about.

Catalyst Configuration Files

So, when you start your Catalyst app, it reads myapp.conf.  Or myapp.yaml or myapp.json or myapp.ini, or myapp.json, or myapp.xml.

There’a  a bunch of common file types it tries until it finds one that works. Generally this part Just Works and you can get on with things.

Multiple Configurations

I needed to be able to specify an additional file to read, though.  I have a development environment, each of the two other developers on the project has a development environment and we have a production environment.

I wrote a clever little thing that would read all the config files in the config directory and find the one that matched the hostname and directory your application was running in, and then include that configuration file.  Neat, automatic, and it allwoed us to check all our config files in to source control.

I actually wrote this as part of the framework I was using prior to Catalyst, and wedged it in to Catalyst as I ported. It’s not perfect.  It keeps breaking.  It was sometimes hard to debug.  (hostname returned odd things on Mac OS X, for instance.)

A post on the Catalyst mailing list the other day had pointed out the Catalyst preferred way of doing this, and I decided I’d move that way the next time I was in that code. I’m sure that everyone involved with this project is competent enough to set an environment variable before they start their servers.

Today, I was in the code, and decided to change it. I then started trying to read the documentation for ConfigLoader, which even has a separate manual page.

I didn’t find anywhere in the manual page that mentioned how the filenames are constructed.  The word “suffix” in the variable names suggested it should be last… instead of the extension to determine file type?  After it?  Before it? Seperated by dots?

I tried them all and got nothing. Then I read the source code, which didn’t get me what I needed easily.

I finally made a test app, copied the module in to the lib directory for it and added a mess of debug code to figure out what file names would actually be read, and dumped the configuration to see what happened. I found it is myapp_suffix.type, where suffix is MYAPP_CONFIG_LOCAL_SUFFIX or CATALYST_CONFIG_LOCAL_SUFFIX or “local” if neither of those is defined and type is one of the many file types that ConfigLoader will try.

Hopefully others will find this entry and not have to spend two hours of their own.

I ought to consider trying to get the documentation updated, but I don’t have much idea how.


3 Responses to “Catalyst and local configuration files”

  1. Tomas Doran says:

    “I ought to consider trying to get the documentation updated, but I don’t have much idea how.”

    Yes! Please please please do!

    The most optimum thing would be if you could send the mailing list a patch to the documentation from subversion
    ( , or even just some text and where you think
    it should go – that’d be amazing!

    Thanks in advance

    • Laufeyjarson says:

      I’ve done so. Being a perfectionist, it took longer than I expected, but it’s done and hopefully no one else will have to spend time untangling it.

      Thanks for the direction, t0m!

  2. […] addition to asking a question, and getting a lot of fantastic help, I followed up on a prior suggestion here on this very blog, that I update the documents for a component of Catalyst.  I took the time […]

Leave a Reply