Building and deploying Mojolicious projects guide

by

I recently had to write some Mojolicious documentation for my final year project and for $work and I decided to use some of the knowledge I gained to put this guide together. It will hopefully help others who might be confused about how to get started using Mojolicious with Carton and Plenv. By no means I believe it is complete and I know some more experienced Perl developers will want to correct some or point out some mistakes.

This structure assumes your project is named ExampleApp, therefore controllers and other files will use this notation. In real examples, the files may be called something different.

Table of Contents

Project structure

Mojolicious Application Structure

  • lib/
    • ExampleApp
      • Controller/*.pm
      • Controller.pm
        • Result/*.pm
      • Result.pm
      • Schema/*.pm
    • Schema.pm
    • ExampleApp.pm
  • local/
  • log/
    • /development.log
    • /production.log
  • public/
  • script/example_app
  • t/
  • templates/
    • /layouts/
    • /example_app/
  • vendor/
  • cpanfile
  • cpanfile.snapshot
  • example_app.conf
  • The lib folder is the main folder, contains most logic, controller and models.
  • Each Controller has .pm file, and potentially sub-controllers which go in folders under the same name. Schema folder holds Model information (DB Schemas, Results and ResultSets)
  • The local folder may appear on production machines. It contains local installations of dependency modules for this project. Managed and installed through Carton.
  • log is Logging folder, usually has a development.log and production.log file.
  • All external files go in the public folder (Bootstrap, JS files, fonts, images etc). Can have any sub-structure.
  • scripts contains the scripts that can be run using the controllers and their actions. By default, it has the main application start script which starts the application by loading files from the lib folder.
  • All tests go in here t/ (if there are any). They all end in the .t extension, but may be grouped in folders.
  • Page templates (for the View) which are structured according to the Controllers go into templates/
  • cpanfile is the Dependencies definition file, specifies what perl module/packages this project relies on. Makes installing dependencies easier as the dependency installer can go through the list and their dependencies as well automatically.

What is CPAN/MetaCPAN?

The Comprehensive Perl Archive Network (CPAN) is a repository of over 250,000 software modules and accompanying documentation for 39,000 distributions, written in the Perl programming language by over 12,000 contributors. CPAN can denote either the archive network itself, or the Perl program that acts as an interface to the network and as an automated software installer (somewhat like a package manager). Most software on CPAN is free and open source software.

Links:

CPAN can be installed as a Linux module under system Perl environment with

$ curl -L https://cpanmin.us | perl - --sudo App::cpanminus

Or, if a Perl environment manager like plenv or perlbrew is installed, with

$ curl -L https://cpanmin.us | perl - App::cpanminus

Plenv has a shortcut for installing cpanm too:

$ plenv install-cpanm

After installing cpanm, to use it for installing a specific module system wide run:

$ cpanm Module::Name

How does Mojolicious work with CPAN?

Mojolicious applications may use and re-use Perl modules available on CPAN. Some of these are written especially for Mojolicious, but most modules are written to be framework and project agnostic, so they can be “plug-n-play”.

Any Perl module (.pm file) may use other Perl modules by including them at the top of the time or inline by writing this line use Perl::ModuleName. This will work just fine if the user already has that module installed on their machine, but on new machines, the module may not be installed and the application will fail to start. That is why most Perl applications keep track of their dependencies in a cpanfile.

Most Perl applications and projects keep track of their dependencies in a cpanfile file. These can be installed with cpanm and/or Carton.

Mojolicious projects also uses the cpanfile to keep track of their dependency, but it’s up to the user to keep the cpanfile up to date. A user may request the general package or a specific version of it, in order to ensure the project runs correctly and newer versions don’t break functionality.

Cpanfile example

requires 'Mojolicious', '== 6.66';
requires 'DBIx::Class';
requires 'Carp';
requires 'DBI';
requires 'Mojo::JSON';
requires 'Minion', '== 5.03';
requires 'Mojo::Pg', 2.18;

To install all dependencies for a project one can run the following command while in the project directory:

$ cpanm --installdeps .

This command will install all dependencies globally. However there are other ways to manage dependencies, using Carton.

By default, all modules are installed under system Perl (the Perl version installed on the machine you are using). If you plan on using Plenv or perlbrew, make sure the modules are installed under the Perl environment and version you need, otherwise your application may not recognise they are installed.

What is Plenv?

https://github.com/tokuhirom/plenv

Use plenv to install, manage and pick a Perl version for your application and guarantee that your development environment matches production. Put plenv to work with Carton for painless Perl upgrades and bulletproof deployments.

When and why would one use Plenv?

Plenv manages multiple Perl environments. For instance, let’s assume the production machine runs Perl 5.20.1 and that cannot be changed because some other applications running on that server rely on it. Your new application requires a newer version of Perl, namely 5.22.0. Plenv can install and manage any Perl version and allow your new application to run using the newer version with little hassle.

It also helps developers test features locally, if their local version of Perl is different than the one in production.

How to install and use Plenv

A full Plenv installation guide is available here:

https://github.com/tokuhirom/plenv#installation

After installing a new Perl version, one can switch between them locally with

$ plenv local 5.22.0

Or globally:

$ plenv global 5.22.0

After any change or module installation it’s recommended you run:

$ plenv rehash

The version of Perl the application will use can be forced/overridden by specifying the PLENV_VERSION Environment Variable when the application is run. E.g.

$ PLENV_VERSION=5.20.1 plenv exec carton exec script/example_app

What is Carton?

https://github.com/perl-carton/carton

Carton is a command line tool to track the Perl module dependencies for your Perl application. Dependencies are declared using cpanfile format, and the managed dependencies are tracked in a cpanfile.snapshot file, which is meant to be version controlled, and the snapshot file allows other developers of your application will have the exact same versions of the modules.

With Carton installed, a developer can download all dependencies locally, and Carton will put them in the local/ directory. Carton will look into the cpanfile file for the dependencies your project needs.

What does Carton exactly do?

It does a couple of things and the developer can choose how they use it, but mainly it manages the dependencies. Here is in a few lines how it can be used and what it can be used for:

  • Carton keeps track of the packages and dependencies’ versions required for your application to run correctly (in the cpanfile.snapshot file)
  • Carton can download and install those dependencies in a local directory, without interfering with other projects that might need other versions of the same dependencies.
  • Carton can create a bundle with those dependencies that you can push as part of your project to make sure no matter what happens to remote source, you always have the versions you tested your app with and know it works.

One can choose to do only 1 and 2, or all three.

Why would I use Carton?

Some might question what are the benefits of using Carton over CPANM.

There are many reasons, but here are some:

  1. If your dependencies suddenly becomes unavailable to download from the internet, you can use the bundle you have with the right versions you know will work (or have tested the application against).
  2. You ensure your project’s independency of other factors (network offline, packages include breaking changes etc).
  3. You make sure everyone in your development team works with the exact same dependencies and their versions, putting an end to “But it works on my machine” arguments.
  4. Sometimes your dependency’s dependencies may become unavailable in which case you might end up with a broken dependency. Carton makes sure you have everything you need.

Carton can be used instead of cpanm and in conjunction with Plenv. Instead of cpanm doesn’t mean you don’t need cpanminus installed, as Carton uses it to fetch the dependencies. It only means you will no longer use cpanm as a command to install and manage a project’s dependencies.

Understanding Mojolicious deployment modes

As mentioned before and as the Mojolicious project structure shows, Mojolicious apps (often referred as Mojo apps) can be run either in development mode or in production mode.

Development is more verbose and allows better debugging, exposes sensitive data and dumps cookies, params and sensitive database connection, which is why it is not recommended for use in production. To run a Mojo app in development mode, use morbo command, which runs in foreground.

$ morbo script/example_app

In contrast, production mode will fail without exposing sensitive data, but it also makes hot deployment easier. To run a Mojo app in production mode, use the hypnotoad command to spin up a process that will be tracked and run in the background.

$ hypnotoad script/example_app

To stop it, pass the -soption. To hot deploy it, after making your changes re-run the command above and hypnotoad will make sure you have zero downtime.

Based on the mode you’re running the application, Mojolicious will read the main example_app.conf file and the mode specific configuration file and combine them. You don’t need to have separate config files, but they can prove useful.

How to deploy a Mojolicious project?

Deployment outline:

Set up the system with Plenv.

This is not a mandatory step, so consult with the project README file or make sure you’re aware of the ways the machine you’re deploying to is set up.

For how to set up the Plenv environment refer to “What is Plenv?” section.

Pull the repository using git.

$ git pull http://github.com/user/example-app.git

Mojolicious – and Perl applications in general – use a cpanfile to determine what Perl dependencies need to be installed. It is the user’s responsibility to keep the cpanfile updated with all the packages they are including in their applications.

Obviously Perl will need to be installed on the server that you will run the application on. On top of that, the application’s dependencies will need to be installed as well.

If using Plenv, make sure you prepend all commands with the plenv version you need (or set it locally/globally) as well as plenv exec.

To install the dependencies one will need to have cpanminus installed. Cpanminus is a dependency installer for Linux based systems. For more information please refer to “What is CPANM/MetaCPAN?” section.

$ cpanm --installdeps .

Alternatively, if the developer used Carton to manage the dependencies, use the carton command to install the dependencies. Append with –cached if you want to use the included modules from the project bundle. For more information please refer to “What is Carton?” section

$ carton install --deployment

How do I know if the developer used Carton?

Check the project structure and look for hints of Carton (highlighted optional folders and file). Generally a cpanfile.snapshot is a clear evidence you should be using Carton to manage dependencies.

Always use Carton if available instead of cpanm. When using Carton prepend your run command with carton exec to let the application know it should use the Carton fetched and installed packages.

Configuration files

Mojolicious applications can run in two modes – development and production – and one can specify a main config file as well as separate deployment mode config files. Mojolicious will read both the main config file as well as the mode-specific config file and combine those. For more information please refer to “Understanding Mojolicious deployment modes” section.

Because they normally include sensitive data, the config files are normally not committed with the repository. Instead, a sample file is provided. Here is an example of a sample main config file which shows what goes.

{
 # Hypnotoad configuration
 hypnotoad => {
   listen  => ['http://*:5555/'],
   workers => 2,
 },

 #OAuth2 List of emails permitted to log in, one per line
 permitted => [
   qw/
   /
 ]
};

The sample mode-specific should give you an idea of what the application’s config file needs to contain in order to run. This may contain database connection information, for instance.

{
 # OAuth2 Key and Secret for Authentication
 key    => '',
 secret => '',

 # Master DB connection details:
 dbname => '', #your_db_name
 schema => '', #your_schema_name Leave blank if in public
 host   => '', #your_host/#ip
 user   => '', #your_user
 pass   => '', #user_pass
};

Make sure your machine has access to the database you’re trying to connect to, otherwise you will get an error when loading the pages.

Run the web server

Mojolicious applications can be run as CGI or as web servers. Mojolicious comes with two solutions, morbo which is meant to be used in development and hypnotoad which is a production web server tool which allows really simple server reload and hot deployment, without ever taking it down.

All following commands can be run under different Plenv environments and in conjunction with Carton so you might need to append the right commands.

Development

For development go into the project top level folder and run

$ morbo script/example_app

This will start the server in development mode, and by default running on port :3000. To stop it, just Ctrl+C it. You can override the port the application listens to by passing on the -l “https://*:3001” option to the command.

Production

For production run the following command:

$ hypnotoad script/example_app

This will start the server in production mode and keep in in the background. You make make changes to the files and folder, but they will only take effect when you reload/hot deploy the server again by re-running the same command. Hypnotoad will spin up another instance before it shuts down the previous one ensuring the server has zero downtime.

To stop the server just run:

$ hypnotoad -s script/example_app

If used with Plenv and Carton you’d probably need to run something like:

$ PLENV_VERSION=5.22.0 plenv exec carton exec hypnotoad script/example_app

Where is the projects’ logs information?

By default, Mojo applications don’t save the log in production mode, whereas in development mode it just dumps it to the console. To make sure you save the log, create a log folder in the projects and the application will save all logs in either development.log or production.log file.

Please refer to the Project Structure section for more information on log folder.

For more information consult the Mojolicious Documentation.