Ask Reuben

Starting With Genero Application Server

What is GAS?

When is GAS required?

Do I need a Web Server?

How can I tell if GAS is installed and configured correctly?

Why won’t my Web Application / Web Service run?

What is a Session?

What is JGAS ?

When developers start using our newer products I often see them jumping in the deep end, trying to run before they can walk, biting off more they can chew etc. and their first experiences are not as positive as they can be. Over time I am going to do a series of articles entitled “Starting …” where I will explain what I think are the key concepts and points you should understand with our products and try to make your initial experience a positive one. Today I will look at Genero Application Server (or GAS).

Most of you will come from a background of using GDC with Direct Connection, you will first encounter Genero Application Server (known as GAS) when you want to …

  • Use the Genero Desktop Client (GDC) via HTTP
  • Use Genero Browser Client (GBC)
  • Provide Web Services (GAS is not needed to consume Web Services)
  • Use runOnServer with Genero Mobile

You can think of GAS as having to do two things.

  • Start your Genero applications (fglrun processes)
  • Manage the communication between a Web Server and the fglrun process

So when a user types a URL into a browser, or clicks on a link, or another program makes a web service call to consume your web service, the GAS is responsible for starting the appropriate program (fglrun) if needed, and managing the communication backwards and forwards between the fglrun process and …

  • the GDC in the case of a program running GDC via HTTP
  • the browser in the case of a program running using the Genero Browser Client
  • the web service consumer in the case of a Web Service
  • the Genero Mobile container app in the case of runOnServer

1. There is no single GAS process.

Study the architecture overview, key thing to note is there is no single GAS process.   Similarly look in $FGLASDIR/bin, there are many processes including those with “dispatch” and “proxy” in their name which correspond to the GAS Dispatcher and VMProxy in the diagram.  This architecture of dispatchers and proxies aids the reliability of the Genero Application Server.  Some of you may remember the early versions of Genero Application Server which consisted of a single executable “gasd” but the problem with this was that if anything happened to this process everything stopped.  Having the separate dispatcher and proxy processes makes GAS more robust.

2. Web Server required for production

A Web Server is recommended for production and can sit on the same server or different servers than the Genero Application Server installation as per these examples.

A Web Server also gives you https, load balancing, authentication.  This functionality is not repeated inside Genero Application Server, we leave that to the web server.

3. httpdispatch is for development

The httpdispatch dispatcher process is intended for development use only.  It acts as a light Web Server, listening for requests and processing them.

The default port number it listens on is 6394

It saves you having a fully configured Web Server in your development environment.   For staging / QA/ production sites you would be expected to use fastcgidispatch , typically in conjunction with Apache Web Server, or isapidispatch in conjunction with IIS in Windows environments.

4. Installation Tests

After installing Genero Application Server, there is a quick test you can do to verify the installation.

At a terminal window, execute the following …

cd $FGLASDIR
. ./envas
cd bin
httpdispatch

The envas script sets the minimum environment needed.

The httpdispatch process starts listening for requests

Then in a browser on the same machine, type the following URL …

http://localhost:6394/demos.html

…. You should see the following …

… if you see this landing page, this tells me that Genero Application Server has been installed, and has been configured so that httpdispatch is listening and responding to requests.

The next step is to click on Genero Demos (or type http://localhost:6394/ua/r/gwc-demo into a browser).  This will start the demo Genero application that is shipped inside $FGLDIR/demo.

… if you see the above this tells me that not only has Genero Application Server been installed but so has a Genero runtime and it has been configured and licensed correctly to enable the running of Genero applications.

5. The Main configuration file ($FGLASDIR/etc/as.xcf)

When a dispatcher process is launched, it will read the file $FGLASDIR/etc/as.xcf as the main configuration file.  You can override this file used in two ways …

  1. you can specify an alternate file by using the -f / –filename argument with the dispatcher
  2. you can override an individual resource entry in the file by using the -E / –resource-overwrite argument

The -E argument is handy when you want multiple dispatchers that may differ in a few things and save having a duplicate file that is nearly identical.

The values in this main configuration file are read when the dispatcher starts and retained for the use of the dispatcher.

There are more details on the main configuration file here and I also find this reference handy.

I would expect you to have your own configuration file that is read using the -f argument.

6. Web Application and Web Service .xcf files

You can specify individual web applications and web services in the main configuraiton file but that means each time you want to make a change to these you have to stop and restart the dispatcher.

What you can do is specify individual application and service configuration files that hold what is unique to each web application and web service.  These files also have the extension .xcf and have a smaller list of configurable entries that are unique for web applications and web services.

The Web Service .xcf is used to configure Web Services as the name suggests.  The Web Application .xcf file is used to configure not only web applications in a browser but also Genero applications being rendered via the GDC using HTTP, and via Genero Mobile apps via runOnServer.

Note: It can get confusing when talking about the various .xcf files, the configuration file passed as an argument to the dispatcher will typically be referred to as “the configuration file”, “the .xcf”, “the main configuration file”

7. Avoiding Duplication in the Configuration Files

The design of the various configuration files avoids defining things more than once.  You can see this in the RESOURCE concept.  Here you can define values that will be used throughout the configuration files.  If you need to change a value, typically you will find that you have to change a resource entry.  These can also be overwritten by use of the -E argument when launching the dispatcher.

The other area you will see duplication avoided is via use of Abstract parents.  If you find the gwc-demo application entry in FGLASDIR/etc/as.xcf you will see it says this parent can be found in the same file , this is an abstract parent that defines what is unique about all web applications. i.e they all use the same FGLDIR, PATH, FGLLDPATH variables and so this is defined once in the parent rather than repeated for each application.

A key skill in interpreting an .xcf is understanding these resources and abstract parents to figure out what is in use.  That is looking upwards to find where a particular resource is defined or  how the abstract parent application is configured.

8. Log Files

The dispatcher and proxy process write log files as they go.  These are invaluable in analysing issues.  Interpreting them will be another Ask-Reuben but for now understand these key points …

  • Log files are by default located in $FGLASDIR/appdata/log/yyyymmdd, this location ( as well as the content and detail) can be changed via configuration file entries
  • When interpreting, read dispatcher, proxy logs as well as the VM logs (stdout/stderr from your running Genero application), and also consider access and error logs from the Web Server.
  • You can get more detail in the logs file by changing the CATEGORIES_FILTER entry to include “ALL”, at the cost of taking up more space.
  • At the top of dispatcher, proxy logs, we will include some uname and environment variable values to help in our analysis.

9. How to start a Web Application or Web Service from a URL

One of the key functions in the configuration file is to provide the functionality that turns a URL received and starts a Genero web application or Genero  web service.

From the URL you need to determine what

  • .xcf is used
  • what EXECUTION node is used
  • and then what environment is set to execute a particular command from a certain directory.

If the URL contains a group entry e..g …/ua/r/mygroup/myapp then a web application or web service is in use.  The corresponding GROUP entry in the main configuration .xcf will tell you what directory this application/service .xcf is located.  The filename will be myapp.xcf.  You will find some examples if you search for .xcf files beneath $FGLDIR

If the URL does not contain a group e.g. ua/r/myapp then either their is an application or service .xcf file in the default group entry, or the application is defined in the main configuration .xcf  file with Id=”myapp”

Once you have the .xcf, you need to find the EXECUTION node.  The EXECUTION nodes have different parameters (for an application or for a service)  The Using attribute will tell you if there are inherited values in an abstract parent node.  The abstract parent application will be defined in the main configuration .xcf.   In $FGLASDIR/etc/as.xcf find the entry with Id=”gwc-demo”, this is used to execute the demo from FGLDIR/demo.

Finally once you have an expanded EXECUTION node, you will see that there are entries for ENVIRONMENT, PATH, DVM, MODULE, PARAMETERS.  These combine to do the equivalent of

export ENVIRONMENT 
cd PATH
DVM MODULE PARAMETERS

Note: that DVM does not have to be fglrun.

So one of the key skills to master is to be able to determine from the URL what application or service is started and vice versa for this application that is running, what determined the environment, path, and process that was executed.

10. How is the environment determined?

One of the most common errors developers make when starting out with GAS is not appreciating that they have to define ALL the environment variables their applications needs in the .xcf.  This typically manifests itself when the program attempts to connect to the database and the appropriate environment variable has not been set for the database connection.

You may get lucky when using httpdispatch, in that a particular environment variable is set in the environment in which httpdispatch is launched and is then inherited by the fglrun process when it is launched.  However when you goto a production web server you may find that the environment variable has not been defined.

It is a good habit to make sure that ALL the required environment variables required are set in the .xcf files.

It is also a good idea to have in your application, a means to dump the environment so that you can see what it actually is.    Even something as simple as a command line argument that will lead to  RUN "env | sort > /tmp/name.env" being executed will suffice.

When you do this you may notice that FGLSERVER is set.  You don’t have to explicitly set FGLSERVER, but this is pointing to the proxy process.   Just as the fglrun talks to the GDC at the port and location determined by FGLSERVER, then in a GAS environment fglrun is doing the same only instead of the GDC directly listening, it is the proxy process on the other end.

11. Who is running the process?

Similar to the environment not being set, the other thing that catches developers out when moving to Genero application server is the process owner of the fglrun process.

With GDC+Direct Connection, the end-user is effectively logging onto the back-end server and running applications as themselves.

When using Genero Application Server, the process owner of the dispatch process is effectively launching the fglrun process and in the O/S eyes is the owner of the fglrun process.  You typically have a special user setup for this purpose.  When first moving to Genero application server, you have to be conscious of permissions and environment variables such as HOME and make sure you take them into consideration in your code.

12. The Monitor

From the demos page you will also an entry Monitoring data that takes you to the /monitor URL .

… your system administrators will need to be familiar with this page.  This allows you to check the status of the dispatcher and proxy processes.

If you can’t see this page, review the ALLOW_FROM entry in the MONITOR section of configuration file.  You will normally need to amend this to allow access to your system administrators if they are not using a browser running on the server.

13. What Is A Session?

When looking at log files and in the monitor you will see reference to a session.

In the case of a Web Application, the fglrun process and any child fglrun processes it launches are considered a session.  This is one uaproxy process with one uaproxy log file, and also corresponds to the consumption of one runtime license.

In the case of a Web Service, this corresponds a single gwsproxy process and the multiple fglrun processes launched to provide that particular web service.    The Service Pools and POOL provide more details on how many fglrun processes are launched and when.

A session id is a big long randomly generated hexadecimal string.  You will see it in the name of the uaproxy log files e.g. “uaproxy-733832e7f36ddcce3ce13d29e3325737.log” and when you look through the logs they form part of the internal URL.

14. gasadmin

Genero system administrators should be familiar with is the gasadmin script.  I think the options to stop and close sessions are under utilised, particularly when deliberately stopping dispatchers.

When you stop the dispatcher it is an opportunity to make sure there are no stray sessions remaining. (and if there frequently are, try and figure out why they are remaining)

15. Multiple Instances

You can run multiple dispatcher instances on the same server.  Reasons may include running multiple versions, or running multiple instances for different developers or different customers.  The key thing is to take note of this documentation entry and make sure that each instance is using a separate port  and directories.  That is you might use port 6394 to talk to one instance of the dispatcher and you might use port 6395 to talk to another instance of the dispatcher.

I will cover this in more detail in a later Ask Reuben as in particular it is not good if the same session directory is used and it makes analysis difficult if the logs are written to the same log directory.  If you have any trouble, this troubleshooting documentation is the first place to look.

16. Additional Environment Variables

A number of details from the Web Server and dispatcher and proxy process are injected into the fglrun process in the form of environment variables.  Read more about these here.

17. What is JGAS?

JGAS or Genero Application Server for Java is an implementation of the Genero Application Server written in Java.  It can be used to deploy and run your Genero applications on Java Enterprise servers.  Read more about this here

18. Summary

If you have not used GAS before I hope this gives some background information as to what the Genero Application Server is and does.

When moving on from GDC+Direct Connection, you will need to use Genero Application Server, wether that is for web, web services, or runOnServer.