Compojure on GAE

Using the App Engine Users API from Clojure

Wed, 09 Jun 2010 09:30:07 -0700

In my previous post about Accessing the Datastore I set up basic security using a security-constraint element in the deployment descriptor (web.xml). This was simple, as the app didn’t have to be aware of security concerns at all. The downside is that the app doesn’t know if the user is logged in and can’t react to that. For example, the “Create new post” link is shown to all users, only after clicking it (and logging in) they get an ugly error message about missing privileges. This is bad usability, so let’s use the App Engine Users API and move the authentication and authorization into the app.

Setting up the routes

To make things easier, I changed my route definitions, separating the public routes from those that need admin privileges. All admin route URLs now start with /admin:

(defroutes public-routes
  (GET "/" [] (main-page)))

(defroutes admin-routes
  (GET  "/admin/new"  [] (render-page "New Post" new-form))
  (POST "/admin/post" [title body] (create-post title body)))

The admin-routes are only allowed to be accessed by logged-in users with admin privileges.appengine-clj already comes with two middleware functions that help with this: wrap-with-user-info adds references to the UserService and (if a user is logged in) User objects from the App Engine API to each request. wrap-requiring-login checks that the user is logged in before passing the request on to the wrapped handler – if not, the user is redirected to the login page.

There’s no wrap-requiring-admin (yet), so I quickly wrote it myself:

(defn wrap-requiring-admin [application]
  (fn [request]
    (let [{:keys [user-service]} (users/user-info request)]
      (if (.isUserAdmin user-service)
        (application request)
        {:status 403 :body "Access denied. You must be logged in as admin user!"}))))

wrap-requiring-admin depends on wrap-requiring-login, which in turn depends on wrap-with-user-info, so I have to decorate my admin-routes handler with all three:

(wrap! admin-routes
       wrap-requiring-admin
       users/wrap-requiring-login
       users/wrap-with-user-info)

Finally, the routes are combined into my main handler:

(defroutes example
  public-routes
  (ANY "/admin/*" [] admin-routes)
  (route/not-found "Page not found"))

Why can’t I just put admin-routes in there, just like public-routes? The problem is, that the middleware I wrapped around admin-routes jumps in before the route-matching. So even if admin-routes can’t match the request URL and passes on control to the next handler, it first makes sure that the user is logged in as an admin. In this case, the not-found handler (which always has to be last) could only be reached by admins, all other users would have to login and then get a 403 error when they enter a non-existing URL. Therefor, I have to make sure that the admin-routes handler is only called for URLs starting with /admin.

Checking the users login status

So far, the new code does the same thing the old configuration did, I haven’t won anything. So let’s make the site a little more dynamic and change the output depending on the users login status. I changed the sidebar to display information about the current user and login/logout links. Also, the “Create new post” link is only shown for logged-in admin users:

(defn side-bar []
  (let [ui (users/user-info)]
    [:div#sidebar
     [:h3 "Current User"]
     (if-let [user (:user ui)]
       [:ul
        [:li "Logged in as " (.getEmail user)]
        [:li (link-to (.createLogoutURL (:user-service ui) "/") "Logout")]]
       [:ul
        [:li "Not logged in"]
        [:li (link-to (.createLoginURL (:user-service ui) "/") "Login")]]
       )
     [:h3 "Navigation"]
     [:ul
      [:li (link-to "/" "Main page")]
      (if (and (:user ui) (.isUserAdmin (:user-service ui)))
        [:li (link-to "/admin/new" "Create new post (Admin only)")])]
     [:h3 "External Links"]
     [:ul
      [:li (link-to "http://compojureongae.posterous.com/" "Blog")]
      [:li (link-to "http://github.com/christianberg/compojureongae" "Source Code")]]]))

(Note that side-bar now is a function, since the content is dynamic.)

I’ve achieved my goals: I can login and logout and I only see the links I’m allowed to click. I can run this code using the local dev_server and I can deploy it to the Google servers (see my previous post on how to do this).

But in the interactive development environment I set up in my last post, nothing works! I’m always logged out and the login link is broken. Let’s fix that.

Making logins work in interactive development

The local implementation of the App Engine Users API calls an instance of ApiProxy$Environment, which I have to provide, to figure out if a user is logged in. In my last post, I set up a very minimal proxy, that always answers this question with “no”. Here’s the relevant snippet:

        env-proxy (proxy [ApiProxy$Environment] []
                    (isLoggedIn [] false)
                    (getRequestNamespace [] "")
                    (getDefaultNamespace [] "")
                    (getAttributes [] att)
                    (getAppId [] "_local_"))

This needs to be smarter. I decided to store information about the current user globally in an atom. Of course, this implies that the server can only be used by one user at a time – for a production system this would be an incredibly stupid implementation, for local development I think it’s ok. Other options would be to store the login information in session variables or directly in a cookie. Storing it globally has the advantage, though, that I can easily view and modify the current login state from the REPL, which eases debugging (plus it’s simple to implement!).

Here’s the definition of the atom holding the login information, prefilled with some reasonable default values:

(def login-info (atom {:logged-in? false
                       :admin? false
                       :email ""
                       :auth-domain ""}))

The updated Environment proxy just reads from the atom:

(defn- set-app-engine-environment []
  "Sets up the App Engine environment for the current thread."
  (let [att (HashMap. {"com.google.appengine.server_url_key"
                       (str "http://localhost:" *port*)})
        env-proxy (proxy [ApiProxy$Environment] []
                    (isLoggedIn [] (:logged-in? @login-info))
                    (getEmail [] (:email @login-info))
                    (getAuthDomain [] (:auth-domain @login-info))
                    (isAdmin [] (:admin? @login-info))
                    (getRequestNamespace [] "")
                    (getDefaultNamespace [] "")
                    (getAttributes [] att)
                    (getAppId [] "_local_"))]
    (ApiProxy/setEnvironmentForCurrentThread env-proxy)))

I added two helper functions to easily modify the atom:

(defn login
  ([email] (login email false))
  ([email admin?] (swap! login-info merge {:email email
                                           :logged-in? true
                                           :admin? admin?})))

(defn logout []
  (swap! login-info merge {:email ""
                           :logged-in? false
                           :admin? false}))

Now I can login and logout by calling the functions from the REPL and the pages served by my Jetty server immediately reflect this. But the login and logout links are still broken. I need to define handlers for these:

(defroutes login-routes
  (GET "/_ah/login" [continue] (login-form continue))
  (POST "/_ah/login" [action email isAdmin continue] (do (if (= action "Log In")
                                                           (login email (boolean isAdmin))
                                                           (logout))
                                                         (redirect continue)))
  (GET "/_ah/logout" [continue] (do (logout)
                                    (redirect continue))))

The login-form function just builds an exact copy of the login page provided by the Google dev_server.

Last but not least, I have to update the start-server function to combine these handlers with my app (the change is in line 9):

(defn start-server [app]
  "Initializes the App Engine services and (re-)starts a Jetty server
   running the supplied ring app, wrapping it to enable App Engine API use
   and serving of static files."
  (set-app-engine-delegate "/tmp")
  (swap! *server* (fn [instance]
                   (when instance
                     (.stop instance))
                   (let [app (-> (routes login-routes app)
                                 (wrap-local-app-engine)
                                 (wrap-file "./war")
                                 (wrap-file-info))]
                     (run-jetty app {:port *port*
                                     :join? false})))))

That’s all – a functioning local implementation of the Users API complete with working login page. I hope you enjoy it!

As always, the complete source code can be found on Github, the version as of this writing is here. You can see the deployed app here (of course I’m the only admin user, so you might want to try it locally to see the full functionality…). Questions and suggestions are very welcome in the comments below!

Permalink | Leave a comment »

Getting interactive development to work (again)

Fri, 04 Jun 2010 04:55:00 -0700

In my last post, I promised to fix my local development setup to enable the interactive development style typical for Clojure and make the App Engine services (such as the datastore) available from the REPL.

Others have already tackled the same problem. The best resource I found is the hackers with attitude blog, another one is here. My code is largely based on these contributions, I rolled my own version mainly to get a better understanding of the setup.

Initializing the App Engine services

To use the App Engine APIs outside of the Google servers, a local ApiProxy and Environment needs to be provided. While the ApiProxy needs to be initialized only once per JVM, the Environment needs to be set for every thread on which API calls are made. This is trivial for the REPL, which runs in one thread. It’s a bit more work when you want to run a local Jetty server, since it spawns new threads for handling requests. Fortunately, the design of Ring makes it easy to add so-called middleware to an existing web app that can handle the environment setup.

Enough said, here’s the code. I’ll go through it def by def below.

(ns local-dev
  "Tools for local development.
   Enables the use of the App Engine APIs on the REPL and in a local Jetty instance."
  (:use ring.adapter.jetty
        [ring.middleware file file-info])
  (:import [java.io File]
           [java.util HashMap]
           [com.google.apphosting.api ApiProxy ApiProxy$Environment]
           [com.google.appengine.tools.development
            ApiProxyLocalFactory
            LocalServerEnvironment]))

(defonce *server* (atom nil))
(def *port* 8181)

(defn- set-app-engine-environment []
  "Sets up the App Engine environment for the current thread."
  (let [att (HashMap. {"com.google.appengine.server_url_key"
                       (str "http://localhost:" *port*)})
        env-proxy (proxy [ApiProxy$Environment] []
                    (isLoggedIn [] false)
                    (getRequestNamespace [] "")
                    (getDefaultNamespace [] "")
                    (getAttributes [] att)
                    (getAppId [] "_local_"))]
    (ApiProxy/setEnvironmentForCurrentThread env-proxy)))

(defn- set-app-engine-delegate [dir]
  "Initializes the App Engine services. Needs to be run (at least) per JVM."
  (let [local-env (proxy [LocalServerEnvironment] []
                    (getAppDir [] (File. dir))
                    (getAddress [] "localhost")
                    (getPort [] *port*)
                    (waitForServerToStart [] nil))
        api-proxy (.create (ApiProxyLocalFactory.)
                           local-env)]
    (ApiProxy/setDelegate api-proxy)))

(defn init-app-engine
  "Initializes the App Engine services and sets up the environment. To be called from the REPL."
  ([] (init-app-engine "/tmp"))
  ([dir]
     (set-app-engine-delegate dir)
     (set-app-engine-environment)))

(defn wrap-local-app-engine [app]
  "Wraps a ring app to enable the use of App Engine Services."
  (fn [req]
    (set-app-engine-environment)
    (app req)))

(defn start-server [app]
  "Initializes the App Engine services and (re-)starts a Jetty server
   running the supplied ring app, wrapping it to enable App Engine API use
   and serving of static files."
  (set-app-engine-delegate "/tmp")
  (swap! *server* (fn [instance]
                   (when instance
                     (.stop instance))
                   (let [app (-> app
                                 (wrap-local-app-engine)
                                 (wrap-file "./war")
                                 (wrap-file-info))]
                     (run-jetty app {:port *port*
                                     :join? false})))))

(defn stop-server []
  "Stops the local Jetty server."
  (swap! *server* #(when % (.stop %))))

The code is in a separate namespace, so it doesn’t get AOT-compiled and deployed with the rest of the app. I’m using an atom to store the Jetty server instance. Using defonce was helpful while developing this, because I could recompile the file (C-c C-k in Emacs) without losing the reference to the running Jetty server.

The two functions set-app-engine-environment and set-app-engine-delegate do the necessary setup work on the per-thread and per-jvm basis, respectively.

init-app-engine just calls these two functions. It’s intended to be called from the REPL, after which you’re able to use API calls like create-entity in the REPL.

wrap-local-app-engine is a Ring middleware that sets the environment for the current thread before passing the request on to the wrapped Ring (or Compojure) app.

The start-server function takes a Ring app, does the per-JVM setup, wraps the app with the middleware for the per-thread setup and starts a Jetty server running the app. If there already is a Jetty server stored in the atom, it is stopped first, so you can use the function to restart the Jetty as well. The :join? false argument is important, otherwise the call to run-jetty will not return.

I also added the wrap-file middleware to serve static files (and wrap-file-info to add Content-Type and Content-Length headers). This mimics the behaviour of the Google servers, which by default serve all files included in the war directory. (Note that, unlike the Google servers, this setup also serves the files in the WEB-INF directory. In a production system that would be a security concern, for local development I don’t mind.)

Last (and also least interesting), the stop-server function stops the Jetty server (and sets the atom back to nil).

Setting up the classpath

To use the local API implementations we need some additional jars on the classpath. Here’s the updated project.clj:

(defproject compojureongae "0.2.0"
  :description "Example app for deployoing Compojure on Google App Engine"
  :namespaces [compojureongae.core]
  :dependencies [[compojure "0.4.0-RC3"]
                 [ring/ring-servlet "0.2.1"]
                 [hiccup "0.2.4"]
                 [appengine "0.2"]
                 [com.google.appengine/appengine-api-1.0-sdk "1.3.4"]
                 [com.google.appengine/appengine-api-labs "1.3.4"]]
  :dev-dependencies [[swank-clojure "1.2.0"]
                     [ring/ring-jetty-adapter "0.2.0"]
                     [com.google.appengine/appengine-local-runtime "1.3.4"]
                     [com.google.appengine/appengine-api-stubs "1.3.4"]]
  :compile-path "war/WEB-INF/classes"
  :library-path "war/WEB-INF/lib")

The new dependencies go into dev-dependencies, since they mustn’t be deployed with the app. However, in the current development version of Leiningen 1.2 (which separates dependencies and dev-dependencies into different directories), the dev-dependencies are apparently only intended for Leiningen plugins such as swank-clojure – they are not put on the classpath for the REPL. I had to patch Leiningen to make this work. Here’s the diff:

diff --git a/src/leiningen/classpath.clj b/src/leiningen/classpath.clj
index 3be7e1f..836740e 100644
--- a/src/leiningen/classpath.clj
+++ b/src/leiningen/classpath.clj
@@ -8,7 +8,9 @@
   "Returns a seq of Files for all the jars in the project's library directory."
   [project]
   (filter #(.endsWith (.getName %) ".jar")
-          (file-seq (file (:library-path project)))))
+          (concat
+           (file-seq (file (:library-path project)))
+           (file-seq (file (str (:root project) "/lib/dev"))))))
 
 (defn make-path
   "Constructs an ant Path object from Files and strings."

I’ll try to get this (or something similar) into Leiningen. Update: I wasn’t the only one with this problem. It was recently patched in Leiningen. Stable Leiningen (1.1) will probably work out of the box – I haven’t tried.

Running lein deps installs the new dependencies. As I said in my last post, you’ll likely have to manually install the jars from the App Engine SDK into your local Maven repository. Here’s an example command for one of the jars:

1
2
3

mvn install:install-file -DgroupId=com.google.appengine \
-DartifactId=appengine-api-labs -Dversion=1.3.4 -Dpackaging=jar \
-Dfile=$GAESDK/lib/user/appengine-api-labs-1.3.4.jar

Putting it to use

Run lein swank, enter M-x slime-connect in Emacs to connect to the REPL and code away as usual. To call functions that make use of the App Engine API, enter this in the REPL:

1 2	(require 'local-dev) (local-dev/init-app-engine)

To start a Jetty server, just enter:

1	(local-dev/start-server (var example))

example is the name of the Compojure app defined by defroutes in core.clj. Update: Using var here allows you to change the definition of example itself without having to restart the server.

What’s next?

The next thing I’m working on is using the Users API for authentication and authorization (instead of the simple security-constraint method described in my last post). I’ll need to make some changes to this local-dev code in order to properly test that locally. So stay tuned…

As always, questions and suggestions are very welcome in the comments section below!

Permalink | Leave a comment »

Accessing the App Engine Datastore

Tue, 01 Jun 2010 05:51:00 -0700

In my last post, I managed to deploy a Compojure app to Google App Engine. Serving static content isn’t very exciting, though. Pretty much every app will need some way to store and retrieve data. So let’s try to access the App Engine Datastore.

New Dependencies

To use the datastore API I need to include a jar that comes with the GAE SDK in my app. I could call the Java API directly, but there are already a few Clojure libraries that provide friendly wrappers around it. One of the first (that I know of) was appengine-clj by John Hume (who was also one of the first to write about using Clojure on GAE).

I decided to go with this fork of appengine-clj by Roman Scherer, which seems to be more complete and actively maintained. Another interesting option would be clj-gae-datastore by the people at freiheit.com.

I updated my project.clj file with the new dependencies:

(defproject compojureongae "0.2.0"
  :description "Example app for deployoing Compojure on Google App Engine"
  :namespaces [compojureongae.core]
  :dependencies [[compojure "0.4.0-RC3"]
                 [ring/ring-servlet "0.2.1"]
                 [hiccup "0.2.4"]
                 [appengine "0.2"]
                 [com.google.appengine/appengine-api-1.0-sdk "1.3.4"]]
  :dev-dependencies [[swank-clojure "1.2.0"]]
  :compile-path "war/WEB-INF/classes"
  :library-path "war/WEB-INF/lib")

I’m using Hiccup (formerly part of Compojure) for HTML generation. Running lein deps runs into an error, because it can’t find the Google SDK jar in the public repositories. Luckily, Leiningen (or Maven) already tells me how to fix this by installing the jar from the SDK download into my local Maven repository – I just have to copy and paste the command from the error message and enter the path to the local jar. After that, lein deps executes cleanly and copies the new dependencies into my lib dir.

Along with updating the dependencies in project.clj I have to import the needed symbols into my namespace:

(ns compojureongae.core
  (:gen-class :extends javax.servlet.http.HttpServlet)
  (:use compojure.core
        [ring.util.servlet   :only [defservice]]
        [ring.util.response  :only [redirect]]
        [hiccup.core         :only [h html]]
        [hiccup.page-helpers :only [doctype include-css link-to xhtml-tag]]
        [hiccup.form-helpers :only [form-to text-area text-field]])
  (:import (com.google.appengine.api.datastore Query))
  (:require [compojure.route          :as route]
            [appengine.datastore.core :as ds]))

The choice of using :use or :require is pretty arbitrary in this case – I just used both to demonstrate the different options. With :require I need to call the functions using the full namespace (using a short alias), with :use they are imported into my namespace. For the latter case, I explicitly named all the definitions I need using :only. This is pretty verbose and not strictly necessary, but for a little howto like this I want you to immediately see where every function comes from, so you don’t have to rummage through all the libraries (although the doc function makes this easy…). I guess it generally is a good idea to not clutter your namespace with definitions you don’t need.

Storing Data

Now comes the more interesting part: Actually accessing the datastore. I want to be able to create simple blog posts, consisting of a title and a body. I need two new routes, one for displaying a form, and one that is used as the action URL for the form:

(defroutes example
  (GET "/" [] (main-page))
  (GET "/new" [] (render-page "New Post" new-form))
  (POST "/post" [title body] (create-post title body))
  (route/not-found "Page not found"))

Here’s the code that handles the form submission:

(defn create-post [title body]
  "Stores a new post in the datastore and issues an HTTP Redirect to the main page."
  (ds/create-entity {:kind "post" :title title :body body})
  (redirect "/"))

Amazingly simple. The create-entity function just takes a Clojure map, which needs to have a “:kind” entry, and stores it in the datastore. After that I issue an HTTP redirect to the main page.

Retrieving Data

Retrieving data is just as simple. On the main page, I just display all posts:

(defn render-post [post]
  "Renders a post to HTML."
  [:div
   [:h2 (h (:title post))]
   [:p (h (:body post))]])

(defn get-posts []
  "Returns all posts stored in the datastore."
  (ds/find-all (Query. "post")))

(defn main-page []
  "Renders the main page by displaying all posts."
  (render-page "Compojure on GAE"
    (map render-post (get-posts))))

The h function takes care of escaping special characters in the user input, so I don’t run into any cross-site scripting trouble. render-page is a little helper function that takes care of constructing the common HTML around the payload for all pages.

As usual, the whole code can be found at Github. The version as of this writing is here.

Basic Security

I don’t want the whole world to be able to post to my blog, so I need some authentication and authorization. I could use the App Engine Users API, but I’ll leave that for a later post. Instead I’ll go the simple route and enable security for some URLs in the deployment descriptor. That way the application itself is blissfully unaware of it. I just need to add this to the web.xml file:

  <security-constraint>
    <web-resource-collection>
      <url-pattern>/new</url-pattern>
      <url-pattern>/post</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>admin</role-name>
    </auth-constraint>
  </security-constraint>

Now only logged-in admin users can post new entries. You can see the deployed version of the app here: http://v0-2.latest.compojureongae.appspot.com/

What about the REPL!?

Okay, everything works fine. I can compile the project, start the dev_appserver to test it locally and deploy it to the Google cloud (see my last post for the steps). But what about interactive development? When I try to call e.g. the create-entity function from a REPL, I only get an Exception. So I can develop and deploy working software, but I’m back to the dreaded edit-compile-run cycle – that’s not the Clojure way.

I need to fix this, but it’ll have to wait until the next post. Sorry…

Permalink | Leave a comment »

Deploying to App Engine

Tue, 11 May 2010 09:59:00 -0700

In my last post, I set up a basic Hello World Compojure app, running on a local Jetty instance. Now I want to deploy this to Google App Engine.

Creating a Servlet

App Engine expects a standard Java web application, which means we have to take a small step out of pure Clojure-land into the Java realm and implement the HttpServlet interface. The defservice macro from the ring API makes this trivial.

Obviously, Google runs their own app servers, so we don't need to start a Jetty instance. The updated core.clj looks like this:

(ns compojureongae.core
  (:gen-class :extends javax.servlet.http.HttpServlet)
  (:use compojure.core
        ring.util.servlet)
  (:require [compojure.route :as route]))

(defroutes example
  (GET "/" [] "<h1>Hello World Wide Web!</h1>")
  (route/not-found "Page not found"))

(defservice example)

The project.clj file needs to be updated to reflect the changed dependencies:

(defproject compojureongae "0.1.0"
  :description "Example app for deployoing Compojure on Google App Engine"
  :namespaces [compojureongae.core]
  :dependencies [[compojure "0.4.0-SNAPSHOT"]
                 [ring/ring-servlet "0.2.1"]]
  :dev-dependencies [[leiningen/lein-swank "1.2.0-SNAPSHOT"]]
  :compile-path "war/WEB-INF/classes"
  :library-path "war/WEB-INF/lib")

Note that I added a :namespaces entry. This triggers the AOT compilation of the Clojure source into Java bytecode. [Edit] I also customized some paths - more on that below. [/Edit]

Google App Engine requires two config files, web.xml and appengine-web.xml. For my simple app, these are pretty straight-forward. The web.xml defines the mapping from URL patterns to servlet classes. Here it is:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app 
   xmlns="http://java.sun.com/xml/ns/javaee" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
   version="2.5"> 
  <display-name>Compojure on GAE</display-name>
  
  <servlet>
    <servlet-name>blog</servlet-name>
    <servlet-class>compojureongae.core</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>blog</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>
</web-app>

The servlet name ("blog") is a generic identifier, you can use anything you like. The servlet-class needs to be the clojure namespace that implements the HttpServlet interface - in this case compojureongae.core.

In the appengine-web.xml we set the GAE application id and an arbitrary version string:

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <!-- Replace this with your application id from http://appengine.google.com -->
  <application>compojureongae</application>

  <version>v0-1</version>

</appengine-web-app>

I set up a github repository for my experiments at http://github.com/christianberg/compojureongae

The code as of the time of this blog post can be found at http://github.com/christianberg/compojureongae/tree/v0.1.1

Building the war

[Update]

Sometimes things are much easier than they first appear. My initial "build process" (using leiningen-war) was way too complicated. Thanks to http://buntin.org/2010/03/02/leiningen-clojure-google-app-engine-interesting/ for putting me on the right track. Here's how I do it now:

The deployment artifact for GAE is a standard java war file - actually a war directory, i.e. an unzipped war file. This makes the build process pretty trivial, you just have to adhere to the standard war directory structure. This is accomplished by customizing the :library-path and :compile-path in the project.clj (see above). Building the project is simply done with the standard lein commands:

lein clean

lein deps

lein compile

The current stable version of leiningen (1.1.0) mixes the dependencies and the dev-dependencies. If you don't want the dev-dependency jars included in your deployment, run this sequence of commands before deploying:

lein clean

lein deps skip

lein compile

The development version of leiningen (1.2.0-SNAPSHOT) separates the dev-dependencies into lib/dev, so you might want to check it out.

[/Update]

Now we have a war directory that can be used by the scripts that come with the App Engine SDK. If you haven't yet, download it now.

Testing the war

To make sure our war file is ok, let's test it locally. I unpacked the SDK in the directory $GAESDK. Here's how to start the local server:

$GAESDK/bin/dev_appserver.sh war

You should see the familiar page at http://localhost:8080/

Into the Cloud!

It's time to deploy. Just run

$GAESDK/bin/appcfg.sh update war

Enter your Google login when prompted and wait for the app to deploy. (Remember that you need to create an Application in the GAE admin dashboard first and put it's app id in the appengine-web.xml.)

The app is now live in the cloud. You can see my deployed version here:

http://v0-1.latest.compojureongae.appspot.com/

Have fun! If this inspires you to do your own experiments with Clojure on App Engine, leave a comment below!

Permalink | Leave a comment »

A Fresh Start

Fri, 07 May 2010 04:59:00 -0700

Since my last post a lot has happened in Clojure- and Compojure-Land. Managing dependencies and building projects is much easier now that there is Leiningen and more people have played around with Clojure on Google App Engine, some are even deploying live apps (check out TheDeadline).

So I decided to build upon these great contributions and (finally) continue this little tutorial.

Create a new project

From my last post, you can still read the part about Emacs, but you can forget about getting all the dependencies. We'll use Leiningen for that. To install Leiningen, follow the installation instructions. Then create a new project:

lein new compojureongae

This creates the basic directory structure with some skeleton code. Edit the project.clj file to look like this:

(defproject compojureongae "0.1.0-SNAPSHOT"
  :description "Example app for deployoing Compojure on Google App Engine"
  :dependencies [[compojure "0.4.0-SNAPSHOT"]
                 [ring/ring-jetty-adapter "0.2.0"]]
  :dev-dependencies [[leiningen/lein-swank "1.1.0"]])

I removed the direct dependencies on clojure and clojure-contrib, since depending on compojure automatically pulls these, but you could leave them in (e.g. if you need a specific version). The dev-dependency on lein-swank gives me integration with Emacs while letting leiningen handle the classpath config.

Running

lein deps

(in the directory containing project.clj) downloads all required libraries and puts them in the lib directory.

Start Hacking

Run

lein swank

to start a REPL, open Emacs and enter

M-x slime-connect

to connect to the REPL. Now we can start hacking away in Emacs! Open src/compojureongae/core.clj and enter the following:

(ns compojureongae.core
  (:use compojure.core
        ring.adapter.jetty)
  (:require [compojure.route :as route]))

(defroutes example
  (GET "/" [] "<h1>Hello World Wide Web!</h1>")
  (route/not-found "Page not found"))

(run-jetty example {:port 8080})

(This is taken directly from Compojure's Getting Started page.) Pressing C-c C-k compiles the file and starts the server - you can see the output in the shell where you ran lein swank. Now browse to http://localhost:8080/ to see your first Compojure app.

Next step: Deploying this to Google App Engine!

Permalink | Leave a comment »

Setting up the Dev Environment

Sat, 24 Oct 2009 07:44:00 -0700

In this post I'll cover the setup I use for developing my Compojure/GAE app.

Emacs
Of course you can use any editor you like to edit your source code, but Emacs has some great features for editing Lisp code that make developing in Clojure a pure joy. When properly set up, you can add new or modify existing code and inspect all your data while the application is running.

I followed the instructions at http://technomancy.us/126 to set up Slime/Swank for Clojure and it worked flawlessly without any modifications. I can also recommend the Emacs Starter Kit that is mentioned in the above post.

Clojure
There are several options for getting the clojure.jar that you'll need:

Download it from http://code.google.com/p/clojure/downloads/list
Clone the git repository at git://github.com/richhickey/clojure.git and build from source using ant
If you're using Emacs and followed the instructions above, you can automatically download the source and build it using the clojure-install command.
Compojure provides a zip file of its dependendies (see below), this also includes clojure

Compojure
You can download a tarball of the Compojure sources from http://github.com/weavejester/compojure/downloads, but I'd recommend cloning the git repository at git://github.com/weavejester/compojure.git. Either way you'll build the compojure.jar from source using ant.

Compojure has a few dependencies. You can download a zip file containing all needed jars (including clojure.jar and clojure-contrib.jar) from the download link above, or you can just run ant dep, which will download the zip for you.

Google App Engine SDK
Download the latest GAE SDK from http://code.google.com/intl/de-DE/appengine/downloads.html. Choose the SDK for Java and unzip it somewhere.

In the next post I'll create a simplistic Hello World Compojure app.

Permalink | Leave a comment »

Compojure on GAE: What's this about?

Thu, 08 Oct 2009 05:13:00 -0700

I'm interested in the Clojure programming language and the Google App Engine platform right now, and I'm playing around with the combination of both. Since there isn't a whole lot of information on this on the net, I thought I'd share the results of my experiments in this blog. Here's the rundown on what this will (and won't) be about:

Clojure
Clojure is a functional programming language of the Lisp family, designed with concurrency in mind to make it easy to write multi-threaded programs. It runs on the Java Virtual Machine and can call (and be called from) Java code. I'm not going to write a tutorial on programming Clojure (many others can do this better than me) nor am I going to try to convince you that Clojure is the greatest language in the world. I just think it's very interesting and I assume you do, too - otherwise you probably wouldn't have stumbled across this site. If you want to learn more about Clojure, the official website provides very good documentation. I highly recommend watching the videos of Rich Hickey's talks, they got me hooked in the first place.

Compojure
Compojure is one of the frameworks for developing web applications in Clojure that are being developed right now. I don't know if it's the best, but it's the one I'm playing around with. The documentation isn't very extensive, but you can find some at http://preview.compojure.org and there's an active Google group. You can grab the code at GitHub. For getting started I recommend this short tutorial by Compojure's creator, James Reeves.

Google App Engine
Google App Engine (GAE) is a service provided by Google that let's you develop web applications that can be deployed to Google's server infrastructure. Google provides several APIs that applications can use, e.g. for user authentication and storing data in a distributed data store. The idea is that applications can easily scale to handle everything from very small to very large loads. When App Engine was initially released it only provided a Python runtime environment. In April 2009 introduced the Java runtime for App Engine. This opened the door not only for Java programs but for a number of languages that run on the JVM, including Clojure.

The example app: A blog! (yawn)
I chose to implement a little blogging application to experiment with Clojure/Compojure on GAE. This isn't very exciting at all and I don't intend to actually use it. But it is simple and straightforward and displays much of the functionality of a typical web app: displaying pages, handling form input, storing and retrieving persistent data and authenticating users. (Edit: After reading this question on stackoverflow I feel a little bad about my choice of example app. But at least I'm in good company...)

So, that's the plan. In the next post I'll talk about setting up the development environment.

Permalink | Leave a comment »