xmpl - an example web application


Meet xmpl, an example web application with flexible deployment possibilities. This post is part of a series.

Every now and then I need to deploy a simple example application to make some tests, e.g. in Kubernetes. So, in time I collected some needs and eventually managed to collapse them all inside a single application: xmpl.

It is based on Mojolicious and, of course, is run by Perl.

If you have a similar need, head over to the README.md file and read what it can do for you! In the meantime, let’s take a quick look at a couple of examples…

A simple key/value store

The basic idea is to provide something dynamic to interact with, with the possibility to make it stateful. For this reason, the basic API that is provided allows manipulating a key-value store.

In the basic level, the key-value store is entirely managed in memory and no access to the filesystem is necessary; this gives the dynamicity of the API, but without sacrificing the possibility to consider the component as stateless.

Whether you consider an application stateful or stateless depends on how you value keeping a persistent copy of the data that are handled.

It’s easy to run an instance that just provides the basic API using the in-memory key/value store (which is a simple Perl hash):

xmpl daemon

The command above will run the application on port 3000, but you can change it of course, e.g. to 3456:

xmpl daemon -l 'http://*:3456'

A persistent key/value store

It’s possible to start the application process and ask it to keep a persistent copy of the key/value store. The application will expose the same exact external API, only data will also be saved to a file and thus it will make it possible to reuse the saved key/pairs across different invocations of the program.

The key is to set the environment variable KVSTORE to a local path:

KVSTORE='./repo.json' xmpl daemon -l 'http://*:4000'

The command above will run an instance of the web application, listening on port 4000 and making sure that the key/value store is saved to file repo.json in the current directory.

A remote key/value store

It’s also possible to chain two (or more!) instances of xmpl using a remote configuration. This means that an instance can be instructed to invoke the API provided by another instance, so that typical topologies with a frontend and a backend can be implemented (even with multiple tiering levels).

Again, they key is to set environment variable KVSTORE, this time with a HTTP/HTTPS URL. As an example, we can connect to the file-backed instance of the previous section like this:

KVSTORE='http://localhost:4000' xmpl daemon -l 'http://*:8080'

This will make the new instance listen on port 8080 and use the instance on port 4000 as its backend.

Use the browser, it works!

The README.md file describes the whole API, but it’s worth noting that you can point the browser to the root of the application and get a page back, that you can use to manipulate the key/value store through normal browser-based interactions (via forms, buttons, etc.).

This is (almost) it!

This is enough for this introduction, further (updated) information can be found in the README.md.

I hope it will be useful for you!

Comments? Octodon, , GitHub, Reddit, or drop me a line!