On the road of making a new Lua Web Framework

by 3scale

It has been nearly one year that 3scale has been acquired by Red Hat. And after releasing our on-premises version, we engineering team, decided to take a week to work on ideas we have but can never work on.


As you may know, 3scale uses its own gateway Apicast to manage the API. It appears to us that Apicast could be used as a Lua web framework. Think about how Ruby on Rails was extracted from Basecamp. Do you get it?

We do not pretend to achieve this in one only week but at least put the base by reaching some goals:

  • Bootstrap your project with a one line command: apicast-cli
  • Install your dependencies easily
  • Run your project in development mode
  • Deploy your project easily on Openshift
  • Ability to run tests against your application

Bootstraping your new project

So let bootstrap our new project. We will assume that you are running OS X and using homebrew. If not, please adapt.

The dependencies

First, we will need to install some dependencies:

  • Luarocks for openresty

    $ brew install apitools/openresty/luarocks

  • apicast-cli

    $ luarocks install apicast-cli


There are for now 3 commands available:

create: bootstraps a new project

server: launches a resty server for your project

busted: runs tests

$ apicast-cli --help
Usage: apicast-cli [-h] <command> ...

Apicast command line utility

   -h, --help            Show this help message and exit.

   c, create             Generates apicast application in a directory.
   s, start              Start Nginx

Apicast command line utility

   -h, --help            Show this help message and exit.

c, create             Generates apicast application in a directory.
s, start              Start Nginx
b, busted             Runs busted tests.

Bootstrap your project

Lets create a new project called myproject

$ apicast-cli create myproject

Generating new project into /Users/hery/Devel/Lua/apicast-cli/myproject
ok /Users/hery/Devel/Lua/apicast-cli/myproject
ok /Users/hery/Devel/Lua/apicast-cli/myproject/.busted
ok /Users/hery/Devel/Lua/apicast-cli/myproject/README.md
ok /Users/hery/Devel/Lua/apicast-cli/myproject/.s2i
ok /Users/hery/Devel/Lua/apicast-cli/myproject/.s2i/environment
ok /Users/hery/Devel/Lua/apicast-cli/myproject/.s2i/bin
ok /Users/hery/Devel/Lua/apicast-cli/myproject/.s2i/bin/run
ok /Users/hery/Devel/Lua/apicast-cli/myproject/config
ok /Users/hery/Devel/Lua/apicast-cli/myproject/config/development.lua
ok /Users/hery/Devel/Lua/apicast-cli/myproject/config/production.lua
ok /Users/hery/Devel/Lua/apicast-cli/myproject/nginx
ok /Users/hery/Devel/Lua/apicast-cli/myproject/nginx/main.conf.liquid
ok /Users/hery/Devel/Lua/apicast-cli/myproject/spec
ok /Users/hery/Devel/Lua/apicast-cli/myproject/spec/myproject_spec.lua
ok /Users/hery/Devel/Lua/apicast-cli/myproject/src/myproject
ok /Users/hery/Devel/Lua/apicast-cli/myproject/src/myproject/init.lua
Generating rockspec for new project

Launching the server

Now you can launch a resty server (default port 8080) with:

$ apicast-cli server -e development

loading config for: development environment from /Users/hery/Devel/Lua/apicast-cli/myproject/config/development.lua
nginx: [alert] lua_code_cache is off; this will hurt performance in /tmp/lua_q3nJ8D:10

There are 2 environment available, production (default) and development.
On development environmet, lua_cache_code is off

You can customize the configuration parameters per environment in config/development.lua and config/production.lua

Lets query it

$ curl -I http://localhost:8080

HTTP/1.1 200 OK
Server: openresty/
Date: Fri, 19 May 2017 12:00:10 GMT
Content-Type: text/plain
Connection: keep-alive

Running tests

Busted is already configured for you to run tests against your application.

Just run:

$ apicast-cli busted

2 successes / 0 failures / 0 errors / 0 pending : 0.000681 seconds

Ready for Docker

s2i build and openshif deployment

The project benefits from Openshift source to image (s2i) so you can easily deploy it on Openshift. And that’s is for free!

Yo can build a Docker image by using s2i command:

$ s2i build . quay.io/3scale/s2i-openresty-centos7:  myproject

And easily deploy it to Openshift:

$ oc new-app quay.io/3scale/s2i-openresty-centos7:[GIT_REPO_URL]

Live application, ApiDocs proxy

At 3scale we reimplemented our ApiDocs proxy with the apicast-cli. You can clone the repo in Github https://github.com/3scale/cors-proxy

Deploying to openshift is a one-liner:

$ oc new-app quay.io/3scale/s2i-openresty-centos7:

And tested against current echo-api:

$ curl 'cors-proxy.staging.3sca.net/foo' -H 'X-Apidocs-Url: https://echo-api.3scale.net' -H 'X-Apidocs-Path: /foo' -H 'X-Apidocs-Query: bar2=ff' -H 'X-Apidocs-Method: PATCH' -d 'body'

  "method": "PATCH",
  "path": "/foo",
  "args": "bar2=ff",
  "body": "body",
  "headers": {
    "HTTP_VERSION": "HTTP/1.1",
    "HTTP_HOST": "echo-api.3scale.net",
    "HTTP_ACCEPT": "*/*",
    "HTTP_USER_AGENT": "curl/7.53.1",
    "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
    "HTTP_X_FORWARDED_PROTO": "https",
    "HTTP_FORWARDED": "for=;host=echo-api.3scale.net;proto=https"
  "uuid": "ff6e6596-23b7-49cf-87a3-198c35330f1a",
  "bodySha1": "Agg/RXngimEkJcDBoX7ket14O5Q=",
  "bodyLength": 4


https://github.com/3scale/apicast-cli is an opensource project under Apache 2.0 License. You are welcome to contribute to it by submitting patches, documentation or creating issues.


Published: May 19 2017

blog comments powered by Disqus