Web App Deployment Details
From Xojo Documentation
Contents
You can create three types of web apps, Stand-alone, CGI and Xojo Cloud. In addition to differences in how they operate, they are also deployed differently.
Stand-alone Application
When you create a stand-along web app, you get a single app that consists of both your app and a standalone web server. This web server listens on the port specified in the Shared Build settings.
To start a stand-alone web app, you launch the app from the command line, terminal or ssh connection. This command runs a standalone web app on macOS or Linux:
./mywebapp
You can run multiple stand-alone web app on the same server, but each web application has to be listening on a unique port and must have unique Application Identifiers. To make it easier to launch on a specific port, you can include the port as a command-line parameter:
./mywebapp --port=8080
If you have the port set at 8080 for example, then you can access the web server using the URL followed by the port like this:
http://www.myserver.com:8080
For more specific information about Linux, refer to UserGuide:Deploy Web App to Linux.
Command Line Parameters
You can use these command-line parameters to change settings when you launch the web app.
 |
Assign values to the parameters using the = separator, not a blank space. For example, to specify a secure port: ./mywebapp --secureport=8100 |
For full details refer to the WebApplication page.
| Command | Description |
|---|---|
| --Port | The standard (not secure) port the web app listens to for a connection. This can be used to change the port that was used to build the web app. |
| --MaxSockets | The maximum number of allowed connected sockets for unsecured connections. This is not the number of maximum users as the number of connections does not map one-to-one with the number of connected users. Do not set the value too high as it will increase memory and CPU usage. The default is 200. If you do not want any unsecured connections, set this value to 0. |
| --SecurePort | The port the web app listens to for a secure connection. You must specify this port via the command-line in order for the web app to allow secure connections. |
| --SslType | Allows you to specify the type of security used. You can use these integer values: 3 (TLSv1), 4 (TLSv11), 5 (TLSv12, the default). |
| --MaxSecureSockets | The maximum number of allowed secure connected sockets. This is not the number of maximum users as the number of connections does not map one-to-one with the number of connected users. Do not set the value too high as it will increase memory and CPU usage. The default is 200. |
| --NetworkInterfaceIndex | The index value (of NetworkInterfaces) to use as the NIC for connections. You can also use the value "Loopback" to allow listening only on the loopback interface. |
| --SecureNetworkInterfaceIndex | The index value (of NetworkInterfaces) to use as the NIC for secure connections. |
| --Certificate | The path to the SSL certificate. |
| --Logging | The path to HTTP Log file. |
Using Port 80
In order to navigate to a stand-alone web app without specifying the port, you need to use port 80, the standard port used by web browsers. However, macOS and Linux do not allow you to use port 80 (or any port lower than 1024) unless you have root access. This means that on macOS and Linux you need to use the sudo command to start your web application if you are using port 80:
sudo ./mywebapp
Note: The sudo command prompts you for your user name and password.
Background Processing
When you run your web app directly from the command line, it will continue running as long as you don’t quit the command/terminal window or log out of the account. This technique does not work well on true servers or remote servers. In these cases you want to run the web app as a background process. On Windows this means, you would run the web app as a Windows Service. On Linux it means you would run it as a Daemon. On macOS, you can run it as a daemon or use the preferred launchd command to start it as a daemon.
Deploying with SSL
In order to deploy a standalone web app so that it uses SSL, you first need an SSL certificate. You can use a self-signed certificate for local testing, but always purchase a real certificate for publicly available web sites. The certificate file used by Xojo is a text file containing the components of your SSL certificate. Generally, a self-signed certificate will have two components (the certificate and key file) while a purchased certificate will likely have three or more (certificate, key, CABundle or intermediates). Create the text file with the same name as your app (minus the app extension if any) and add the ".crt" extension. Then paste the contents of your certificate files in this order:
- Certificate
- CABundle
- Private Key
Start each file on a new line.
This Xojo certificate file must be placed next to the built web app when it runs. This can be done using a Copy Files Build Step with Build Automation. Now you can start your web app and tell it to listen for connections on a secure port. This uses the secureport and maxsecuresockets command-line parameters described in the preceding section. The secure port must be different than the (non-secure) port selected in the Shared Build Settings. It also must be different than a port specified with the port command-line parameter.
For example, if you want to launch your web app on secure port 8081, use this command:
MyWebApp --secureport=8081
Once you have launched the app, you can connect to it in the browser like this (for a web app running locally):
https://127.0.0.1:8081
If you also want to prevent unsecured access to the web app, you can set the number of unsecured sockets to 0:
MyWebApp --secureport=8081 --maxsockets=0
Refer to UserGuide:SSL for Standalone Web Apps for more information.
Windows Service
To run a web app as a Windows Service, you use the sc command from the Command Line to install the app as a service:
sc create MyWebAppSvc type= own start= auto binpath= c:\Path\To\Exe\mywebapp.exe
Now you can go to the Services Manger in the Control Panel and see the “MyWebAppSvc” service listed. Use Services Manager to Start, Stop or Pause the service.
Daemon
To make your stand-alone web app run as a daemon background process, you call the Daemonize method, usually in the App.Open event:
When you now run the stand-alone web app from the terminal, it will immediately return you to the terminal prompt because the app is now running in the background.
This also works on macOS, but Apple prefers that you use the launchd command to start daemons. Using launchd means you have to create a Property List file with the specific settings.
For more information, refer to Apple’s documentation on this:
CGI Application
When you build your web app as a CGI application, you get an executable file that communicates to your existing web server using CGI (common gateway interface). The way this works is that a small Perl CGI script is created when you build your web app. Its only purpose is to communicate between your web app and the web server. The Perl script starts your web app if it is not running and routes all communication between the web server to your web app and vice versa.
When you build your web app for CGI, you have the option of choosing a port or having it be chosen automatically. This is an internal port that is used for communication between the Perl script and your web app. Because this is internal communication, the firewall is not affected. The only requirement is that nothing else on the server is also using the port.
Nearly all web servers support CGI and Perl, but some are much easier to configure than others.
Apache
The most common type of web server you will see is Apache, which is typically preinstalled on Linux servers. Most Apache servers have a specific location where CGI apps should be uploaded. This is often called the “cgi-bin” folder.
On a properly configured web server, deploying a web app is as simple as using your SFTP client of choice to copy the entire web app folder’s contents to the cgi-bin folder (be sure to enable Binary mode for the transfer). The files include:
- The web app itself
- The Resouces folder
- The Libs folder
- config.cfg
- the Perl CGI file
- The .htaccess file (which may be hidden in the default view of your SFTP software)
Then you can start the web app by accessing the cgi script:
http://www.myserver.com/mywebapp.cgi
Xojo does not provide support for configuring your web server for use with Xojo web apps. If you require easy, one-click deployment of your Xojo web apps consider using Xojo Cloud.
Troubleshooting
Unfortunately, not all servers are going to be properly configured to run Xojo web apps. You may find that you have to change the configuration yourself. Below are some common areas to check. Step-by-step instructions are not possible because every installation of Apache is different, having configuration files in different places with different web server users and different permissions. Use these tips as guidelines, but you’ll still need an understanding of Apache and how it has been installed on the OS you are using.
- OS: Verify that you built and uploaded your web app for the correct OS. Although you may be developing and testing on macOS, if you are using a Linux server you need to remember to make sure that you create a Linux build to upload.
- 32-bit Libraries: If your application is a 32-bit application that you want to run on a 64-bit version of Linux, you'll need to ensure the 32-bit compatibility libraries are installed. The command to do this varies depending on the Linux distribution. Refer to Resources:System Requirements for suggestions. With Debian, you can use apt-get:
# apt-get update
# apt-get install ia32-libs-multiarch
- Application Identifier: Verify that the Application Identifier is unique. If there is another web app running on the server with the same Application Identifier, then your new app will not start.
- Permissions: Verify that your CGI application and all the libraries in the Libs folder have been copied to the server and have execute permissions (755 is best). You may also need to check the parent folder as well the config.cfg and Perl CGI script. Permissions of 777 are not secure and some web servers (that use seEXEC) will not run anything with that permission.
- AddHandler: If your web application displays the page source rather than running, you may need to add the command “AddHandler cgi-script .cgi” to your Apache configuration file or to the .htaccess file generated with your web application.
- Internal Server Error: If the Perl CGI script is having trouble starting you may see this error. Verify that Perl is installed correctly and permissions are correct.
- Unable to Launch Application: The Perl CGI script is unable to start your application. Usually you will see additional information such as “permission denied”. Verify that your web application was uploaded using FTP Binary mode (and not ASCII, which can corrupt the application files).
- Unable to Connect to Port: The port may be blocked for some reason. Perhaps the firewall is blocking a local port or the port is in use by another application or service. If you have selected a port, make sure it is > 1024 and < 65536.
- Web Server Logs: Your web server logs may have additional useful information. The location of these logs varies depending on the Linux distribution and version.
- LibICU: Some older versions of Xojo require the libicu library for international text support, which you may need to install manually depending on the version of Linux you are using. Refer to System Requirements for suggestions.
Xojo does not provide support for configuring your web server for use with Xojo web apps. If you require easy, one-click deployment of your Xojo web apps consider using Xojo Cloud.
Deploying with SSL
Because a CGI app uses a separate web server, you have to ensure your web server (typically Apache) is configured to work with SSL and your SSL certificate. You do not have to do anything specific with your Xojo CGI web app in order to deploy it as SSL since SSL is handled by the web server.
IIS (Microsoft Internet Information Services)
Included with Windows is a web server called IIS. This web server is ideally suited for running simple HTML web sites, .NET web applications and other specific Microsoft web products. Xojo recommends using IIS as a reverse proxy to a Standalone Web App. More information is here:
Xojo does not provide support for configuring your web server for use with Xojo web apps. If you require easy, one-click deployment of your Xojo web apps consider using Xojo Cloud.
Xojo Cloud
If all this setup and configuration is too much to bother with, you should consider hosting your web app using Xojo Cloud. This service allows you to deploy a web app directly from Xojo by clicking the Deploy button on the toolbar. With Xojo Cloud, you just check the "Xojo Cloud" target in Build Settings for your web project and then select it to specify the name of the application and the Xojo Cloud server on which to deploy. Then you simply click the Deploy button in the toolbar and your app is built and uploaded to your Xojo Cloud server.
Refer to the UserGuide:Xojo Cloud topic for more information.