Default Directory Structure

The Caribou directory structure is designed to be simple and flexible.
Running tree in the root illuminates the structure:

├── app
│   └── assets
├── project.clj
├── resources
│   ├── cljs
│   │   └── taiga.cljs
│   ├── config
│   │   ├── development.clj
│   │   ├── production.clj
│   │   ├── staging.clj
│   │   └── test.clj
│   ├── public
│   │   ├── css
│   │   │   └── taiga.css
│   │   ├── favicon.ico
│   │   └── js
│   │       └── taiga.js
│   └── templates
│       ├── errors
│       │   ├── 404.html
│       │   └── 500.html
│       └── home.html
├── src
│   └── taiga
│       ├── boot.clj
│       ├── controllers
│       │   └── home.clj
│       ├── core.clj
│       ├── helpers.clj
│       ├── hooks
│       │   └── model.clj
│       ├── migrations
│       │   ├── admin.clj
│       │   ├── default.clj
│       │   └── order.clj
│       └── routes.clj
├── taiga_development.h2.db

There are some main features to take note of for now.


First is the project.clj, which configures lein and holds information about dependencies and plugins. You will be editing this when you want to add a new Clojure library to your project, for instance. Also, this is where you define various options about how the site runs, including the port, the handler and an init function that is run on boot. Full details can be found in the configuration section on project.clj.


The resources directory has four branches: cljs, config, public, and templates.

  • cljsThis directory holds any clojurescript files for your Caribou project. By default these files will be compiled to javascript every time they are changed.
  • configconfig holds all the configuration files for the various environments that your Caribou app will eventually run in. The name of each environment maps to a configuration file with the same name and suffixed by .clj. So in the "development" environment Caribou will use the development.clj config file. For now the app defaults to development, but there are things you will want to shut down for production that are helpful in development, like automatic code reloading. For this Caribou provides a production.clj with its own set of configuration options.
  • publicAnything in public will be accessible as a static resource under the URL that maps to this directory structure. If all you have is static content, just throw a bunch of files in here where you want them to be accessed and you are good to go! We have put some helpful files in here to get you started, (css and js) but nothing is set in stone. Have at!
  • templatesHere is where all of the dynamic templates go. In Caribou, you can create content that can then be accessed from templates. Caribou uses a template engine called Antlers by default.


src holds all of the Clojure files that run your Caribou site. Inside is a directory named after your project (here that is "taiga"). All of your site specific code will go in here.

There are some notable entries in your project source folder:

  • core.cljThis is the entry point into your Caribou project, and ultimately what gets executed on boot. You can change everything about how Caribou runs from inside this file, from replacing pages and models to defining configuration to executing handlers for every request. For now, the structure is set up to run Caribou how it was designed to be run, but never forget that you have ultimate control of this.
  • boot.cljThis file governs which configuration file gets loaded. You can also change configuration options inside this file that apply to all running environments, if you wish.
  • routes.cljHere is where all of the routes of your site are defined. There is a set of routes that are defined directly in code using Polaris and there are routes defined in the database through the Admin which are accessed here as well. For more on routing check out Routes and Pages.
  • helpers.cljHere you can define your own template helpers in addition to the helpers provided by Caribou. A helper is simply a function that is accessed during render time from the template. For more on helpers see the section on Rendering Templates.
  • migrationsThis directory contains data migrations that specify how your data evolves over time. You can add your own migrations in addition to the migrations necessary to run your site for the first time. Any migration files added here must be included in order.clj. This is necessary so that the migration system knows what order to run the migrations in. The database keeps track of which migrations have been run, so no migration is ever run twice on one database.
  • hooksHooks are defined per model. There are a variety of points in the content lifecycle where custom code can be run, if desired. This is covered in the configuration section on hooks.
  • controllersControllers are called when an http request is matched by a page that references that controller. This is how routes are linked to actual Clojure functions that eventually render a template or a return a valid response of some kind.

The default H2 database

This will be named after your project with the suffix "_development.h2.db". By default Caribou uses H2 because it is an all java database which requires no native dependencies. You will probably want to swap this out with your own database backend, but Caribou will work fine if all you ever want to use is H2.