Canto v1834
Community curation
Questions? Contact curators...
Canto installation


Installing with Docker

The recommended method for installating and running Canto to use Docker.

The following commands will install and initialise a Canto instance. The commands retrieve the Canto code, start a temporary Docker container and then initialise Canto.

# this directory can be anywhere and have any name
mkdir canto-space

cd canto-space

mkdir data
mkdir import_export
mkdir logs

git clone

# initialise the data directory 
./canto/script/canto_start_docker --initialise /data

At this point the data directory is initialised and the canto/canto_deploy.yaml Configuration file has been created for this Canto instance.

To test that the installation and initialisation succeeded, use this command to start Canto:


then go to http://localhost:5000/ to check that Canto is running.

Use docker stop canto-container in another terminal to stop the server.

If that works the next step is to configure Canto.

Manual installation on Debian or Ubuntu

If Docker isn't an option for you, it's possible to install and run Canto on a Debian Linux based system. The instructions below should work on both Debian and Ubuntu based systems.

Software requirements for manual installation

The following software is needed:

Supported systems

Canto should be installable on any system that supports the software requirements. These instructions have been tested on Debian (v7.0+) and Ubuntu (v12.04+).

Installing prerequisites on Debian and Ubuntu

On Debian and Ubuntu, the software requirements can be installed using the package manager:

sudo apt-get install perl gcc g++ tar gzip bzip2 make git-core wget \
  libmodule-install-perl libcatalyst-devel-perl liblocal-lib-perl \
  libpq-dev libxml2-dev zlib1g-dev libssl-dev libexpat1-dev

Optional: to improve the installation speed, these Perl packages can be installed before proceeding:

sudo apt-get install libhash-merge-perl \
  libhtml-mason-perl libplack-perl libdbix-class-perl \
  libdbix-class-schema-loader-perl libcatalyst-modules-perl libio-all-lwp-perl \
  libwww-perl libjson-xs-perl libio-all-perl \
  libio-string-perl libmemoize-expirelru-perl libtry-tiny-perl \
  libarchive-zip-perl libtext-csv-xs-perl liblingua-en-inflect-number-perl \
  libcatalyst-modules-perl libmoose-perl libdata-compare-perl \
  libmoosex-role-parameterized-perl libfile-copy-recursive-perl \
  libxml-simple-perl libtext-csv-perl libtest-deep-perl \
  libtext-markdown-perl libchi-driver-memcached-perl libchi-perl \
  libcache-memcached-perl libcache-perl libfile-touch-perl \
  liblwp-protocol-psgi-perl libweb-scraper-perl \
  libdbd-pg-perl libdata-javascript-anon-perl starman libnet-server-perl \
  libautobox-list-util-perl libwant-perl libautobox-core-perl

If these packages aren't installed, the required Perl modules will be installed using CPAN, which is slower.

CLucene is required by Canto. For Debian version 7 ("wheezy") and earlier and Ubuntu version 13.04 ("Raring") and earlier it can be installed with:

sudo apt-get install libclucene-dev libclucene0ldbl

CLucene on Ubuntu v13.10 and later

For these Ubuntu versions the correct version of the CLucene library must be installed manually. The Perl CLucene module is currently only compatible with CLucene version 0.9.* but Ubuntu v13.10 and later ship with CLucene v2.3.3.4.

The required CLucene library can be installed with:

sudo dpkg -i libclucene0ldbl_0.9.21b-2_amd64.deb libclucene-dev_0.9.21b-2_amd64.deb

You may need to "pin" those version in v14.10. For example, add a file called /etc/apt/preferences.d/clucene-pin with these contents:

Package: libclucene0ldbl
Pin: release a=precise
Pin-Priority: 999

Package: libclucene-dev
Pin: release a=precise
Pin-Priority: 999

CLucene on Debian v8 ("Jessie") and later

The CLucene libraries must be manually installed for Debian v8 with:

sudo dpkg -i libclucene0ldbl_0.9.21b-2+b1_amd64.deb libclucene-dev_0.9.21b-2+b1_amd64.deb

Getting the Canto source code

Currently the easiest way to get the code is via GitHub. Run this command to get a copy:

git clone

This creates a directory called "canto". The directory can be updated later with the command:

git pull

Downloading an archive file

Alternatively, GitHub provides archive files for the current version:

Note after unpacking, you'll have a directory called canto-master. The text below assumes canto so:

mv canto-master canto

CPAN tips

It's best to configure the CPAN client before starting the Canto installation. Start it with:


At this prompt choose 'sudo':

What approach do you want?  (Choose 'local::lib', 'sudo' or --> 'manual')

When started, cpan will attempt to configure itself. Usually the default answer at each prompt will work.

Use these commands at the cpan prompt avoid lots of questions while installing modules later.

o conf prerequisites_policy follow
o conf build_requires_install_policy no
o conf commit

Install the Module::Install::Catalyst module (at the cpan prompt):

install Module::Install
install Module::Install::Catalyst

Quit cpan and return to the shell prompt with:


Install dependencies

In the canto directory:

perl Makefile.PL
make installdeps

Answer "yes" to the "Auto-install the X mandatory module(s) from CPAN?" prompt.

Run the tests

To check that all prerequisites are installed and that the code Canto tests pass:

make test

Canto in a Virtual machine

Canto can be tested in a virtual machine using VirtualBox and Vagrant. This combination is available on Linux, MacOS and Windows.

These instructions have been tested on a 64 bit host.

Installing VirtualBox

Installation packages for VirtualBox are available here:

On some operating systems, packages may be available from the default repositories:

Installing Vagrant

Installation instructions for Vagrant are here:

Users of recent versions of Debian and Ubuntu can install with:

apt-get install vagrant

Canto via Vagrant

Once VirtualBox and Vagrant are installed, use these commands to create a virtual machine, install the operating system (Ubuntu) and install Canto and its dependencies:

cd canto
vagrant box add precise64
vagrant up

The vagrant command will take many minutes to complete. If everything is successful, once vagrant up returns you can ssh to the virtual machine with:

vagrant ssh

From that shell, the Canto server can be started with:

cd canto

Once started the server can be accessed on port 5500 of the host: http://localhost:5500/

Testing the manual installation

To try the Canto server after a non-Docker installation:

Initialise a test data directory

Make a data directory somewhere:

mkdir /var/canto-data

From the canto directory:

./script/canto_start --init /var/canto-data

This will initialise the canto-data directory and will create a configuration file (canto_deploy.yaml) in the canto directory that can be customised.

Run a test server

Again, from the canto directory.


Visit the application start page

The test application should now be running at http://localhost:5000

Next step

Setting up Canto