Deployment details
Web apps can be deployed on your own server or on Xojo Cloud. In addition to differences in how they operate, they are also deployed differently.
Starting and accessing your web application
When you create a web app, you get a single application 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 your web app, you launch the app from the command line, terminal or ssh connection. This command runs a web app on macOS or Linux:
./mywebapp
You can run multiple 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 Deploying Web Apps on Linux.
Command Line parameters
You can use these command-line parameters to change settings when you launch the web app.
Note
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 |
|---|---|
--BaseURL |
The application will use the specified folder/directory as the entry point to serve its web pages and resources, allowing the web application to coexist with other applications under the same domain. |
--Certificate |
The path to the SSL certificate. |
--Logging |
The path to where the HTTP Log file is or will be created. |
--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. |
--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. |
--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. The default is to listen on all interfaces. |
--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. |
--SecureNetworkInterfaceIndex |
The index value (of NetworkInterfaces) to use as the NIC for secure connections. The default is to listen on all interfaces. |
--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). |
Using port 80
In order to navigate to a 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 secure web app with 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: 1. 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 SSL for 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.
Running in the background
To make your web app run as a background process on macOS or Linux, you can launch it from the command line like this: ./MyWebApp &
When you now run the web app from the terminal, it will immediately return you to the terminal prompt because the app is now running in the background.
On Linux, you can also use systemd. If you don't want to deal with this level of complication, consider using Xojo Cloud.
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:
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.
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. On macOS and Windows, consider using the logging option in Command Line Parameters above.
Check the permissions for the files and folders containing your web app.
Ensure that the web app and the libraries in the Libs folder are all set to be executable.
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.
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 your 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 Introduction to Xojo Cloud topic for more information.