Coronium 2 - Lua Cloud Server

Coronium 2 is a Lua based cloud framework that offers quick and simple ingredients to build custom cloud functionality for your apps and games.

The stack is compiled and installed using industry standard tools. The process facilitates faster update cycles, community contributions, and best practices. Development is driven by community contributions.

The cloud api itself is very simple to use. Here is an example of a "POST" Routing Method, in this case named echo:

--projects/test/api.lua

local api = cloud.api()

function api.post.echo(input)
  return input
end

return api

This will create an endpoint that will respond to a "POST" request, injest any posted data, and echo it back to the client:

https://your.coronium.instance/test/echo

Stack Overview

As a "stack" Coronium 2 should be considered like other stacks (LAMP, MEAN, etc) in that it should reside on its own server, have full access to resources, and without competing services.

Coronium 2 is built on a variety of industry standard tools including:

• Lua
• OpenResty (Nginx and LuaJit)
• MongoDB
• MySQL
• PHP5-FPM
• Let's Encrypt
• Chef-Solo
• And more.

The Coronium 2 stack is backed by a special cloud api namespace. The api is developed using the Lua programming language, and includes various functionality like:

• Data Management
• File Management
• External Requests
• Content Templating
• Long-Running Jobs
• And more.

Along with many Lua based utility modules like:

• GeoIP
• Time
• Internal
• LPeg
• LuaCrypto
• Moses
• And more.

The Lifecycle

It's important to understand how the "communication" lifecycle works. Coronium 2 is similar to a common web server. It takes in a request and outputs a response. Afer the response is sent, the server (or any web server for that matter) has no idea about the requesting client.*

Without using specific cloud api methods for longer or external running processes, you will lose "context" to your clients original request.

*Unless cookies or sessions used.

The Coronium 2 lifecycle has the following pattern:

<-- Client sends a command to an endpoint

• Lifecycle started

--> Coronium injests the call, with any input data

• Checks Module Auth and Permissions
• If authed run the Routing Method

<-- Coronium return results to requesting client

• Lifecycle done

Getting Started

A quick and free way to test Coronium 2 is using a program that creates a virtual "computer" on your local machine called VirtualBox. You can interact with this virtual machine and develop your cloud based projects quickly.

You will also need Vagrant to control and provision your VirtualBox instances. Both of these programs are available for Mac and Windows and cost nothing to use.

Additonally, make sure to have a text editor and command line program handy. Once you have Vagrant and VirtualBox installed, you can compile the Coronium 2 source code.

Installing From Source

Start by downloading the latest install source archive to your Desktop, or folder of choice.

Decompress the downloaded archive, and using a terminal program, navigate into the deploy/localhost directory:

cd <source>/deploy/localhost
# Start compiling
sudo vagrant up

After about 5-10 minutes you should have a 'pristine' build of Coronium 2 to freely work with.

Logging In

Once the server is provisioned, you can log in via command line. You'll need to do this at least once to start the services.

If using the default, from the command line enter:

ssh cloud@192.168.71.73

Password is cloudadmin

Once you are logged in to the server, run the following when you want to start the cloud processes:

sudo cloud up

You can also "tail" the system logs by entering:

cloud logs

Exit the logging mode at any time by using [Ctrl-C] on your keyboard.

Testing The Server

Once you have Coronium 2 running, you can check the test endpoint. Hopefully it will respond with data. Open up a web browser and enter the following in the location bar:

http://192.168.71.73/echo/test?hello=Coronium

Your browser should output a JSON string object that should look like:

{"result":{"hello":"Coronium"}}

http://192.168.71.73/echo/test?hello=Coronium&fun=true

{"result":{"hello":"Coronium", "fun":true}}

An Example Using Corona SDK

You will need a Corona SDK minimal project set up, and the Corona SDK Module to interact with your Coronium instance.

Download the latest Corona SDK Module

Unpack the module archive and move the coronium folder into your project directory. The structure should look like:

MyProject
  coronium/ --Coronium Module
    cloud.lua --Coronium Classes
    ...
  build.settings
  config.lua
  main.lua
  ...

Add To build.settings

...
android =
{
  usesPermissions =
  {
     "android.permission.INTERNET",
  },
},
...

Wire It Up

Once you have all that in place, open the Corona SDK main.lua and enter the following at the top (or near) of the file:

-- main.lua
require('coronium.cloud'):new({
  host = '192.168.71.73', -- default test host
  project_key = '000000000-0000-0000-000000',
  https = false --no ssl for localhost
})

Congrats! You now have created a new namespace in your Corona SDK environment called cloud.

The cloud namespace holds three methods:

First Contact

Now we can test the Coronium echo Routing Method using Corona SDK. Add the following to the main.lua file:

...

--network listener
local function listener( event )
  if event.phase == 'ended' then
    print(event.response.hello)
  end
end

--cloud request
local req = cloud:request('/echo/test', {hello="Coronium"}, listener)

Run the program. The text "Coronium" should be printed out in the console log.

Cloud Lua

So far we have been mostly looking at the Corona SDK client side of things. Now let's look at what is going on on the Coronium server-side of things. We have been using the Project called echo. The structure looks like so:

/projects
  /echo
    api.lua
    config.lua
    /tpl
      index.tpl

config.lua

Let's look quickly at a default config.lua for the echo project:

--config.lua
local config =
{
  key = "< generated_key >"
}

More config key options are available, see the Client Usage section. The key is generated when running cloud add <projectname> on the server.

The config.key is your "API" key for a specfic project. It must match the key sent by the client module when referencing that project.

api.lua

The api.lua is the central routing point. All client requests and server responses travel through this file.

It's very simple to set up the api.lua file, and amounts to adding methods to HTTP headers, referred to as Routing Methods. You will use the cloud.api object to do this:

An Example users project

--api.lua in "users" project.
--/projects/users/api.lua

--== Lazy code example (needs more error checking)

--get a reference to an API object
local api = cloud.api()

--add Routing Methods Here
--function api.<http_method[post|get]>.< method_name >( [ input ] )

-- Add a user
function api.post.add_user( input )
  local user = input.user
  local access = input.access

  local mongo = cloud.mongo.new()
  local db = mongo:use_db('users')

  local result, error = db.user:insert({user=user, access=access})
  if not result then
    return cloud.error( error )
  end

  return result, nil
end
--== Creates a "/users/add_user" endpoint.

-- Get a user
function api.post.get_user( input )
  local player = input.player

  local mongo = cloud.mongo.new()
  local db = mongo:use_db('users')

  local res, err = db.user.find_one({user="Sally"})
  if not res then
    return cloud.error( err )
  end

  return res, nil
end

--return the API object to the core system
return api

Calling Routing Methods

In Corona SDK you call your routing methods using the Corona SDK Module. For instance:

-- main.lua
require('coronium.cloud'):new({
  host = '192.168.71.73', -- default test host
  project_key = '000000000-0000-0000-000000',
  https = false --no ssl for localhost
})

local function listener( event )
  if event.phase == 'ended' then
    if not event.reponse.error then
      print(event.response)
    end
  end
end

local req = cloud:request('/users/add_user', {user="Sally", access=true}, listener)

Or to retrieve a user:

...

local function listener( event )
  if event.phase == 'ended' then
    print(event.response.access)
  end
end

local req = cloud:request('/users/get_user', {user="Sally"}, listener)

Deployment

See the Deploy section for more details on deploying a Coronium instance.