Deploying a standalone Xojo Web app for the first time may look unfamiliar or confusing. One might look at the built product and wonder where the files are. None of this ends in .asp, .cgi, or .php; and where is index.html?

I promise, this whole package makes things easier for developers. With a Xojo Web app, the built product is the web server. Once it’s running, the web app handles everything for us.

So how does a Xojo Web app get running? There are a few “easy button” solutions. One is, of course, Xojo Cloud the built in service. Additionally, there is at least one third party hosting service dedicated to Xojo Web apps. These tools can simplify deployment, but require that a developer relies on customer service when there’s a problem.

For mission critical applications, DIY-ers, and cost conscious developers the option to deploy to a Linux server might be a more appealing choice.

Creating a Droplet

This instructional is centered around deploying to a Digital Ocean droplet. Some instructions may be specific to CentOS. Translations for other flavors are gladly accepted.

The first step in this journey is to create a droplet to run the web app. Droplets are virtual machines that come pre-configured, and are easy to create and destroy. To begin click “Create” and select “Droplets”.

On the following screen configure the new droplet. My preferred flavor of Linux for servers is CentOS, so for this tutorial select the pre-built CentOS 7 x64 image. Next, select the size and specs of the server.

I have had success testing on a $5/mo droplet, but haven’t yet used one in production. For reference the $10/mo plan matches the specs of Xojo Cloud’s small server. Again, for this tutorial select the $5/mo droplet. The size and specs can be changed later if necessary.

Choose a datacenter location nearby and jump down to the Authentication section. When using SSH Key authentication, Digital Ocean prepares the virtual machine without password entry. This makes the droplet more secure and less vulnerable to brute-force attackers. To configure SSH keys, they offer more detailed instructions here.

Set a hostname that means something and optionally add tags to the droplet. With this, the droplet is ready to be built. Click “Create Droplet”. While the droplet builds will be a great time to configure DNS settings.

Networking

Users are going to expect they can access the web app by visiting domain.com or app.domain.com. To connect a domain name to a web app, the name server records must be configured. Navigate to the domain’s DNS management and add an A record pointing at the brand new droplet.

This is convenient when using Digital Ocean name server features. The new droplet will appear as an option when editing the address field. For name servers managed elsewhere, paste in the IP address of the new droplet.

To allow time for the droplet to complete setup and the name server updates to propagate, it is now safe to step away for a coffee or lunch. The droplet should be ready in about a minute, however DNS records aren’t always so fast. You can check if they’re ready with this tool.

A Quick Break

In this downtime, allow me to sidetrack and talk about my install script. I developed this script to simplify the repetitive tasks of setting up a fresh droplet for a Xojo Web app. It will be used later in this tutorial, and it breezes through quite a few steps.

./install.sh -a AppName -d app.domain.com -e your@email.com

• Installs required libraries and dependencies for Xojo Web
• Installs and configures a firewall
• Installs and configures intrusion prevention software
• Installs and configures a free SSL certificate from LetsEncrypt
• Configures a cron job to automatically renew the SSL certificate
• Configures a systemd service for the web app, which:
• Runs the app in the background so you can logout from the server
• Automatically restarts the app if it crashes
• Automatically starts the app when the server starts
• Script automatically starts the app at the end of install

All of this can be done manually. You could do the research on each step to learn how to do them. You could read blog posts, man entries, StackOverflow, security articles – all the usual – to be sure you understand each one. Or you could buy me dinner 🙂

In exchange for my research and effort developing the simple install script I ask a fair $10 – enough for a nice dinner. Please consider it, the transaction is handled securely by FastSpring, and the script is delivered instantly upon completion.

Buy Install Script

The droplet is probably ready now, back to the install.

Connect and Install

When the droplet is ready and the name server records have been updated, it’s time to connect to the server and upload the app. Droplets come configured with SSH and SFTP installed and active. This makes it easy to connect, upload the web app, and install. There’s some light visible at the end of the tunnel!

First, pack the web app for upload. For this tutorial, the example will be a fresh build of Eddies Electronics. Add install.sh and the templates folder to the build folder from Xojo.

Now connect to the new droplet with SFTP. Most major file transfer apps can connect to SFTP servers. Personally I’m a big fan of Transmit, but Cyberduck is a great free alternative. Connect to either the IP address of the new droplet, or the domain that was just set up. The username will be “root”. Leave the password blank to use SSH key authentication.

Upload the entire build folder including the install script and templates folder. When that’s complete, the next steps are to connect via SSH and run the install script. This will be done with the command line in Terminal.

Connect to the server by typing out this line (change eddies.xojo.dev to your server!)
ssh root@eddies.xojo.dev

Upon successful connection, the beginning of the terminal line should change to the droplet hostname. The example here looks like this:
[root@eddies-electronics ~]#

This will be the home directory for the root user that was signed in. Run the command ls (type that and press enter) to see the file listing for this directory. It should match that of the SFTP app.

Now run the install script, swapping out the Eddies Electronics placeholders with the target application details. You may see messages during the install script as yum imports new keys. This is normal.
EddiesElectronics/install.sh -a EddiesElectronics -d eddies.xojo.dev -e your@email.com

The install script will perform its tasks and finish with a results overview. If there are any issues, the status message will be red. The web app should now be running!

Post Install Management

So what did this all do? How does one start and stop the app? How to do app updates? SSL renewal? The script makes all of this easy by creating a systemd service to run the web app in the background. It uses the name provided with the -a parameter.

For example, stop EddiesElectronics with: systemctl stop EddiesElectronics
Similarly, start it with the verb start: systemctl start EddiesElectronics

Check the status and see any Print messages with the status verb. To update the web app, stop the app service, replace the web app files, and start the app again. Services are great!

LetsEncrypt certificates expire after 90 days to encourage renewals. I am told this makes the internet more secure. The install script sets up a cron job to automatically renew and install certificates. To perform this renewal at any time, run the renew.sh script that is generated next to the install script. This script will stop the app, renew certificates, install the app certificate, and re-start the app.

The install script will configure the server and app to pretty much run themselves. Systemd will restart the app if it crashes, and will start the app when the server starts (after a reboot or shutdown for maintenance). Autorenew SSL will keep the app certificate valid and the app secured.

If you have any questions or I missed something feel free to reach out to me!

Buy Install Script

Tags: Tutorial, Web