Coronium 2 - Lua Cloud Server

Coronium 2

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:


local api = cloud.api()

  return input

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:


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:

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:

Along with many Lua based utility modules like:

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.

Heads Up!

Coronium 2 is not a "real-time" server and cannot be used for games or apps in that genre. It is possible to construct a "turn-based" project though.

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

Learning More

The following is a concise overview on the various aspects of using Coronium 2, with many things left out for brevity. Be sure to read the other sections, especially the User Guide for more in-depth details.

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@

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:

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


Try It Out!

Change the query string -- the ?key=value part -- and watch the results. You can also add more arguments:
{"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:

  coronium/ --Coronium Module
    cloud.lua --Coronium Classes

CoronaSDK Users

Make sure add the Android Network Permissions to your build.settings.

Add To build.settings

android =
  usesPermissions =

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
  host = '', -- 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:

Method Description Documentation
:request Make a request to the cloud system. Click Here
:upload Upload a file to the cloud file system. Click Here
:download Download a file from the cloud file system. Click Here

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

--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

SFTP Connections

At this point you should log in to your SFTP program with the cloud user, password: cloudadmin. The default address is

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:



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

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.


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.

--== 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 input )
  local user = input.user
  local access = input.access

  local mongo =
  local db = mongo:use_db('users')

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

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

-- Get a user
function input )
  local player = input.player

  local mongo =
  local db = mongo:use_db('users')

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

  return res, nil

--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
  host = '', -- 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

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

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


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