FuguHub Your Personal File Sharing Solution

 

FuguHub

Manage Data Your Way

Creating FuguHub Applications

FuguHub is an application server, and it allows anyone with web and server side experience to extend and/or change the server. FuguHub supports a server-side scripting language called Lua Server Pages or LSP for short.

There are many possible applications for FuguHub. One might be a basic HTML form that saves data in a SQL table on a FuguHub server running on Windows. Another might be an advanced device management application on a Raspberry Pi, also powered by FuguHub.

The Lua Scripting Language

Lua Server Pages makes developing web applications extremely fast, simple, safe, and fun. Notably, it isn't limited to developing web applications, but can also be used to provide high-level socket APIs that make developing secure socket applications very easy. We also provide HTTP client libraries, SMTP (mail) libraries, database integration (SQLite is embedded in FuguHub), and other options.

Lua Server Pages are based on the Lua Scripting Language. Getting started with LSP is easy if you have previous experience with similar technologies such as PHP or ASP.

Lua Server Pages Programming API

Since FuguHub is developed by using the Barracuda Application Server C Library, all of the Barracuda Application Server's Lua API's are supported, enabling you to write anything from easy to advanced server side web applications.

Mako Server:
Make sure to also check out the Lua powered Mako Server and Mako Server's online and interactive Lua tutorials. FuguHub and Mako Server are both based on the Barracuda App Server library.

Application Server and Lua

We recommend reading the Barracuda Application Server article What is an Application Server? if you are uncertain about the difference between a web server and an application server or if you are new to writing server side web applications. We also recommend reading the Lua fast-tracks web application development article if you are new to Lua and web design.

Dynamically Generated Pages

Lua Server Pages (LSP) can be freely intermixed with HTML or XML. LSP tags are XML compliant
<?lsp  ?>. Code between these tags is executed as Lua code (as shown in the page counter example to the right). Expressions are provided by the <?lsp=  ?> tag. The result of an expression is emitted as HTML/XML.

LSP Page Counter Example:

<?lsp page.count=page.count and page.count+1 or 1 ?> <html> <body> <p> You are visitor <?lsp=page.count?>. </p> </body> </html>

FuguHub provides Lua bindings (interface from Lua to C code) for the following integrated components: the Barracuda Application Server, SharkSSL SSL/TLS duo stack, Lua Server Pages, SMTP Client, HTTP(S) Client, AJAX, JSON, JSON-RPC, XML-RPC, SOAP Web Services, WebDAV Server, the EventHandler, High Level Secure Sockets, the SQLite Database, the GD Graphics Library, and Lua LPeg. You can dynamically load additional Lua bindings at runtime such as an API to your own hardware, but this requires that you also master C code.

Getting Started With LSP

To get started with FuguHub, install the server on your own computer, but skip the Internet Wizard. The server you install on your own computer will be your test server. You can start developing LSP applications as soon as you have installed the server, but we recommend that you download the API documentation and complete a tutorial before attempting to write any LSP applications.

  1. Download and install FuguHub.
  2. Download the "Barracuda Application Server" documentation badoc.zip.
  3. Download the "Do It Yourself" tutorial diy.zip.
  4. Move the two downloaded files badoc.zip and diy.zip to the FuguHub application directory. The FuguHub's application directory can be found as a sub-directory in the FuguHub installation directory.
  5. Using a browser, navigate to FuguHub, menu, Administrator Panel, Application Manager, Load, and click the load button to load badoc.zip and diy.zip.
  6. FuguHub will add links to the left menu, under section "Loaded Applications" for the documentation and the Do It Yourself Tutorial.
  7. Using FuguHub, complete the Do It Yourself Tutorial and use the loaded documentation for reference.

Using LSP in FuguHub

You have three options when it comes to writing LSP applications in FuguHub.

  1. Use the CMS and add LSP directly into the CMS pages.
  2. Add LSP files to the cmsdocs directory.
  3. Create a new FuguHub application.
Option one is for programmers who want to add basic LSP scripts to web pages created using the CMS. Snippets of LSP code can be added to any page in the CMS by using the CMS editor. However, you cannot currently use the WYSIWYG editor. Open the editor for the page you want to LSP enable and click the advanced button. You will see the HTML code. Enable LSP in the check box at the top. Add your LSP code to the page. The code is automatically executed each time you press the save button.

Option two is for applications that should be an integral part of the CMS web pages. You can add LSP pages directly to the cmsdocs directory and/or to any sub-directory in the cmsdocs directory. For example, creating index.lsp in sub-directory 'shopping' can be access as http://my-server/shopping/ and http://my-server/shopping/index.lsp. Be careful with creating pages with the same name as pages in the CMS. Your own pages take precedence over pages in the CMS. For example, adding page index.lsp directly in the cmsdocs directory replaces the CMS main page when you navigate to your server.

Option three is for standalone or advanced applications. How to create and load new applications are briefly explained in the FuguHub help-file under Administrator Panel, Application Manager, New.

When you create a new application you must first create a new sub directory in the FuguHub installation directory. This directory will be the base for your application. In other words, the web pages for your application are stored in this directory. Using a browser, navigate to FuguHub, menu, Administrator Panel, Application Manager, New. Click the browse button, browse and select your newly created directory. Use the directory name as the "Application Name" and click Submit. On the next page, select LSP and click Submit.

When creating a new application, you will get the option of creating a regular application or a root application. A root application is as the name implies, an application that starts with the URI /. For example, an index.lsp page in the application folder is accessible as http://myserver/. A standard application starts with the base name you selected as the application name. For example, an application named myapp and with index.lsp in the application folder is accessible as http://myserver/myapp/

The CMS delivered with the FuguHub server is configured as a root application. You can easily verify that the CMS is a root application by navigating to http://myserver/. You should see the CMS main page.

FuguHub can load multiple root applications. Resource (name) conflicts are resolved by the application's priority. For example, two root applications with an index.lsp are resolved by executing the index.lsp page in the application with the highest priority. You can dynamically change the priority for any root application by clicking on the root application name in the FuguHub's application list. Note: you can only change the priority for root applications in FuguHub.

You can optionally deploy an application when you have completed the development. Deploying an application is done by zipping all pages and data in your application directory and placing the ZIP file in the FuguHub "applications" folder. Using a browser, navigate to menu, Administrator Panel, Application Manager and stop the development version. Click the Load menu link and then click the load button to load your newly deployed application.

You can also unpack any of the FuguHub applications such as the CMS. You can that way easily modify any of the applications that are delivered with FuguHub. Copy the unpacked content to a new directory and use the Application manager to load the non deployed application. Follow the steps above for creating a new application when loading a non deployed application.

You can remove the LSP applications delivered with FuguHub if you want a complete custom solution. However, the internal user interface (uri /rtl/) cannot be removed. The server will not start if it is unable to load bd.zip.

Creating libraries, re-usable code, or non web applications

At this point you are ready to make your first LSP application(s). The rest of this document is tailored for advanced application design.

FuguHub has the concept of an application environment. The environment for an application is a location where you can keep commonly used Lua code i.e. library functions. This environment is available to LSP pages in the application, but not to LSP pages in other applications. The application environment is referred to as the application table in our documentation. FuguHub provides a number of environments that can be used by LSP programmers. See the "Lua -> overview" in the Barracuda document for more information.

The Lua code is typically not embedded in LSP pages if you write functions that are designed to be re-used by several LSP pages or if you write Lua code that is using the more advanced features of the Barracuda Application Server API's. FuguHub looks for the file ".preload" when loading applications. You can place your generic functions in this file as well as any code that is not directly associated with a web page.

Functions and data in the .preload script are added to the application table. You can access this table from an LSP page as "app". For example a function such as myfunc() can be accessed from an LSP page as app.myfunc().

The .preload scripts are executed when FuguHub starts and when an application is started by using the FuguHub Application Manager. You can use the Application Manager to load your new version at any time during development. Click the stop button and then the start button to reload the script.

When an application is stopped by FuguHub, code in the .preload script will eventually become garbage collected by the Lua virtual machine. However, sometimes you may want to do an immediate action when an application is stopped. FuguHub looks for the function "onunload()" just before stopping an application and executes this function if you have created such a function in your .preload script.

The CMS is a deployed application that has a .preload script internally located in the ZIP file. This file is executed by FuguHub when the CMS starts. The CMS preload script is in turn looking for a .preload script in the cmsdocs directory. You can extend or add your own functions to the CMS by creating a .preload script in the cmsdocs directory. For example, adding a function such as myfunc() to the .preload script in the cmsdocs/ directory can be accessed from LSP enabled CMS pages and LSP pages in the cmsdocs/ directory as app.myfunc().

CMS .preload script example

The following example shows how you can create a custom 404 handler by creating a text file cmsdocs/.preload in an editor and then copying and pasting the following Lua code into the .preload script.

local function my404func(_ENV, relativepath) -- The 404 directory callback function trace("Page not found (404 error)",relativepath) -- Redirect to a page that returns the 404 message -- Make sure you have this page: cmsdocs/my404.lsp if not recursive then recursive=true -- Note: set in the short lived request/response _ENV response:redirect("/my404.lsp") -- Does not return end return false -- not handled end if not _G.my404dir then -- If not globally installed local my404dir = ba.create.dir(-100) -- Create a directory with low priority (-100) my404dir:setfunc(my404func) -- Install the directory service function my404dir:insert() -- Insert "mydir" as a root directory. _G.my404dir=my404dir end

The above example is specifically designed for the CMS .preload script. The cmsdocs directory is chained in such a way that response:forward() cannot find files in the cmsdocs directory. We have to use response:redirect() as an alternate solution. Notice how we have the special construction that prevents recursive calls.

Note: the cmsdocs/my404.lsp must be an LSP page that includes the following LSP code:
<?lsp response:setstatus(404) ?>

Modifying FuguHub's Internal Resources

Starting with FuguHub (BD) 6.0, the server's internal resources can be loaded in non deployed mode. The resource files are located in bd.zip. The following instructions are for unpacking this ZIP file and for requesting BD to load the unpacked (non deployed) resources.

  1. In the BD installation directory, create a new sub directory such as bdzip.
  2. Unzip bd.zip into this directory.
  3. Open a command window in the BD installation directory.
  4. Set the environment variable BD_ZIP=bdzip, where bdzip is the directory where you unpacked bd.zip. For example, use the following command on Windows: set BD_ZIP=bdzip.
  5. Start BD as a foreground process on the command line. For example, use the following command on Windows: bd -console.
  6. You can now actively edit and modify the BD resources using an editor. Pressing the refresh button in the browser reloads your modified content.