Xojo Web: What to Do After You Click Build

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”.

Screenshot shows the location of where to create a new dropplet on the Digital Ocean dashboard.
Create a new Digital Ocean droplet from the dashboard.

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.

Screenshot shows where to create a new A record using Digital Ocean name servers.
Adding an A record using name servers at Digital Ocean

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.

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.

Screenshot of Finder window highlighting the two install script components added to a build of Eddies Electronics

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.

Screenshot of the connection details from the tutorial in Transmit.app

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!

Screenshot of a successful installation in the Terminal window.
Install script completion status message, all systems go!

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!

11 thoughts on “Xojo Web: What to Do After You Click Build”

  1. Thanks Tim.

    A couple of questions if I may?

    Will this script be updated when 2.0 comes out if it’s needed?

    How long is the app offline for when the SSL is renewed? I worry about it taking a while or hanging for a reply and customers getting annoyed.

    Thanks in advance.

    1. Hi Rod,

      Yes, I intend to make any changes necessary for Web 2.0. This system was designed for standalone applications, and we’ve been told the next generation is standalone only. I don’t expect that much, if anything, will need to change 🙂

      It should be under a minute, but I can’t promise any kind of time because it all depends on the communication between your server and letsencrypt. The install script creates a cron job set to occur bi-weekly at 0400 server time. You can adjust that as necessary if you need to, https://crontab.guru can help you write the schedule.

      Best wishes,
      Tim

  2. Hi Tim,
    Thanks a lot.
    Would you have any recommendation for a simple web control panel ?
    I’m looking for a simple way to manage:
    – security updates
    – MySQL / PostgreSQL install/updates
    – server usage stats

    Most of my web apps are running one app/one server and Webmin and other CWP control panel are a bit heavy for those simple tasks.
    Free or cheap solutions preferred.

    Thanks anyway for the script, bought it, installed it, ran a test app in a few minutes !

    Regards,

    Olivier

    1. Hi Oliver,

      I’m glad the script worked out well for you!

      If you’re using DO & CentOS with this script, yum update will keep things up-to-date. I’ve found that there are MySQL and Postgres yum packages, though I didn’t read into how difficult it is to use them.

      I’m a fan of CWP for managing my other websites. I don’t know of any other recommendable free / low cost solutions. I have found (by setting the app port to something unused) that CWP and a Xojo Web app can play on the same server. I would bet with some configuration it’d even be possible to route through nginx; but I’d have to spend some time looking into that.

      Sorry I don’t have a better recommendation for you!

      Best wishes,
      Tim

      1. Hi Tim,

        I’m not using DO but UpCloud whose prices are identical and performances are huge.
        They have powerful APIs, extra fast SSD with MaxIOPS, IPv6, etc.
        Very similar to DO but EU company, servers location in EU, Asia ad US.
        I’ll have a deeper look at CWP.

        Thanks anyway.

        Take care,

        Olivier

  3. Hello,

    very cool tool – I am very impressed.

    Is is possible to use multiple arguments for -d? For example example.com http://www.example.com?

    I did not try it for not breaking https at lets encrypt.

    Thanks for your answer

    Jens

    1. I’m not certain if you’re asking whether you can allow the app to run on http by passing a second argument, or if you’re trying to secure multiple domains for one web app.

      To answer the first scenario, you don’t need to do anything extra. The script prints the https url at the end for convenience. However, the web app is listening on whatever port you set in the build settings. With this set to port 80 both http and https should be working. In an app I’m working on the HandleURL event redirects http requests to https every time.

      The second scenario, I don’t have an answer for. I’m not certain if a Xojo web app can support multiple SSL domains / certificates, I haven’t looked into it at all.

      In either case, the -d parameter is unable to accept multiple values. I never tested what a space might do, so I don’t know how that might turn out.

      Best wishes,
      Tim

Leave a Reply

Your email address will not be published. Required fields are marked *