Chapter 11. Environment Configuration and Deployment

So far, we've built a simple but fairly well-rounded application, hipstr, which performs many of the every-day tasks required by web applications. This chapter will focus on a couple different ways one can deploy a Clojure-based web application, as well as how to abstract the environment configurations that will differ from deployment to deployment. In this chapter, we will cover the following topics:

• environ, a library for reading environment configurations

• How to pass environment variables to our application outside our development environment

• How to deploy our application to a few common setups

By the end of this chapter, you'll know the basics of how to abstract the application's environment configuration, and how to get this thing up and running outside the Leiningen Ring Server plugin. We're almost there. Can you taste it?

Environ

Luminus-generated applications make use of the environ library, which was written by James Reeves, the essential Godfather of Clojure web development (remember, this guy wrote Ring, the Ring Server, and about every other underpinning library we've used in this book). The environ library allows applications to read environment variables set from outside the scope of any internalized configuration. This is important to remember: environ accepts environment configurations only from outside the application, thus adhering to the third tenant (Configuration) of the 12 Factor-Application Pattern.

Note

You can read more about the 12 Factor-Application Pattern at http://12factor.net. While not necessary for this chapter, it's something I encourage any software developer to read, as the practices contained within are beneficial for any software you're writing.

Using environ

Consuming environment configuration through environ is trivial. Let's assume we have an environment variable called DB_USER...

Setting and resolving environment configurations

We've already alluded to the fact that you can set configuration for environ to consume from either environment variables or from Java system properties. This covers about 100% of real-world usage. However, during development, we can also set environment configuration using the lein-environ plugin (which is also packaged as part of a Luminus-generated application).

When running the development server using lein ring server, the lein-environ plugin will fetch environment configuration from the Leiningen project map, as well as an optional profiles.clj file, and merge the two together into the .lein-env file. This .lein-env file is the first go-to place for environment settings, but only when running the development server.

Note

It is recommended that the profiles.clj and .lein-env files not be committed into your version control, as every developer's environment is likely to be somewhat different. Plus, despite the fact that .lein-env supports...

Adjusting the database connection

In essence, the Configuration principle of the 12 Factor-Application Pattern states that an application's configuration and an application's code should be completely independent of each other. Our hipstr application currently violates this principle in a key area: the database connection. This, however, is easily resolved.

Creating the profiles.clj file

For our development server, we will create profiles.clj and have the lein-env plugin generate the .lein-env file. Currently, our hipstr.models.connection/db-spec expects 5 settings: :classname, :subprotocol, :subname, :user, and :password.

Theoretically, we could transfer the entire db-spec map into the profiles.clj file, such as shown below:

{:dev {:env {:db-spec {:classname   "org.postgresql.Driver"
                       :subprotocol "postgresql"
                       :subname     "//localhost/postgres"
                       :user        "hipstr"
                       :password    "p455w0rd})

We could then...

Deploying the hipstr application

The lein-ring plugin can create 2 different types of packages for deployment: an uberjar or an uberwar. These are created using lein ring uberjar or lein ring uberwar respectively:

• uberjar: Creates an executable .jar file containing all dependencies, including an embedded Jetty server

• uberwar: Creates a standard .war file containing all dependencies, which can be deployed to any Java web application server (such as Tomcat or GlassFish)

  Note

  Check out the official lein-ring documentation to get more details about the various options available for ring uberwar/uberjar at https://github.com/weavejester/lein-ring.

How you're going to deploy your application determines how you're going to package your application.

When to use an uberjar

Because Ring applications have an embedded Jetty server, we have the option of creating a self-contained, fully independent uberjar, which contains all the required dependencies and can run on its own. The advantage of this is that...

Summary

In this chapter, we learned how easy it is to abstract our application's configuration away from our application code. We then demonstrated how we can serve our application as a standalone app, using the embedded Jetty server. We also learned how to package an uberwar in case we wanted to deploy to a Java application server, such as GlassFish.

At this point, you have enough knowledge to be able to start writing web applications using Clojure. Did we cover everything? No, but that's why the book isn't 700 pages. However, what we did cover are the essentials, and, anything else from this point forward you should be able to learn while hitting a pint of beer and flicking through web pages on your phone. So go out and write, my friend, and bring peace and joy into this world!