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:
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@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"}}
Try It Out!
Change the query string -- the ?key=value
part -- and watch the results. You can also add more arguments:
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 ...
CoronaSDK Users
Make sure add the Android Network Permissions to your build.settings
.
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:
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 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
SFTP Connections
At this point you should log in to your SFTP program with the cloud
user, password: cloudadmin
. The default address is 192.168.71.73
.
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.