What are GitHub Actions?

If you want to read all about it – head over to their documentation. To get started, you should at least know about the following terms:

Workflow

A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository. 

Job

A job is a set of steps in a workflow that execute on the same runner. Each step is either a shell script that will be executed, or an action that will be run.

Runner

A runner is a machine that runs your workflows when they’re triggered. GitHub provides ready to use runners as preconfigured virtual machines. And of course you can host your own runners.

A GitHub Actions workflow can be configured to be triggered when an event occurs in the repository. So how to leverage that? Let’s talk about the Git Branching strategy that I’m going to use in this example first.

Git Branching Strategy

Using GitHub obviously means the one is using Git as Source Control. There are quite a few common strategies and workflows to use Git. For this example I’ll be using the following:

• Default Branch: main
  I want to make sure that all code in the main branch can be compiled at all times. Every push (or Pull Request against the main branch) should automatically build a Beta Version of the app.
  At some time I want to use the latest commit to build a final version of the application.
• Feature branches: feature/xyz
  To start working on a new feature or bug fix, I’ll create a feature branch. As I often commit I don’t want to build every single commit. There might be commits with “work in progress” which won’t even compile.
  Once ready: I create a Pull Request against the main branch.
• Pull Request (against main branch)
  This means a feature or bug fix is ready. So a GitHub Action should kick in and build the app. If that fails it simply means the feature isn’t ready for the main branch. The built Beta Version can be downloaded to do some more manual tests before merging into the main branch.
  Once the Pull Request is merged (always using a squash commit), this will result in a single commit to the main branch (of the whole new feature). Same procedure: a Beta of the app is automatically built and ready for to download and test.
• Release a Final Build
  After adding couple of new features and bug fixes I want to release a final version.
  Whenever I feel ready, a GitHub Actions Workflow can be started manually. That will build a Final Version, create a Release in the GitHub Repository and upload all Builds to the Release as Assets.

A bit of information before starting to write the GitHub Actions Workflows:

About Workflows

Workflows are defined by a YAML file checked in to the repository in the .github/workflows directory.

YAML files

A word of precaution when writing and editing YAML files:

• Indentation is done by spaces (not by tabs!)
• Indentation has to be exact, or expect to get syntax errors

Xojo GitHub Actions Workflows

According to the Git Branching Strategy I want to build Beta Releases (on Pull Requests and on Push to the main branch), and I want to manually create a Release with a Final Build.

This means that there will be two Workflows:

• Beta Build
• Create Release

They have something in common. Both need to build the Xojo project and execute the postbuild steps. To avoid duplication I’m going to write a reusable workflow:

• Xojo (Build and PostBuild)

A workflow (Beta Build | Create Release) that uses another workflow (Xojo Build and PostBuild) is referred to as a “caller” workflow. The reusable workflow is a “called” workflow.

This ScreenShot shows the Beta Build workflow which calls the reusable Xojo workflow:

The Create Release workflow looks similar during it’s run. It can be started manually on GitHub.

Once finished, a new Release is available in the GitHub repository:

The Set Up

There is quite a bit to do:

• Set up a Build Mac
  A Mac of our own is needed. The reason for that is that Xojo isn’t set up on GitHub’s virtual macOS machines (one would need to download and install it every single time). And even if it were, we would need to setup and register Xojo with a License. And Xojo Licenses take a seat on every machine – so no good idea for a fresh virtual machine on every build.
• Create a Xojo IDE Communicator
  Build Automation with Xojo requires to communicate with the Xojo IDE. I’m going to use the project that Xojo ships in the examples, but modify it a bit.
• Configure the GitHub Repository Settings
  There are settings to enforce the chosen Git Branching Strategy. And there are some settings for GitHub Actions that need to be set up.
• Set up a self-hosted GitHub runner
  Install the GitHub runner on the Build Mac and link it to the repository.
• Xojo Project and Post Build Scripts
  I’m going to add a PreBuild Xojo Script. And of course all Post Build Scripts regarding CodeSigning, Installer creation, packaging, Notarization.
• GitHub Actions: Secrets
  CodeSigning means certificates and passwords. They get their safe place in the repository Secrets.
• GitHub Actions: Workflows
  Once everything is in place… one can finally start writing the actual workflows.

As you can imagine, guiding you through all these steps is going to be quite a lengthy article.

Source Code & Documentation

Should you consider using GitHub Actions with your own Xojo projects, then have a look at this repository: GitHub: jo-tools/xojo-github-actions

It contains the full documentation, the source of the modified Xojo IDE Communicator, an Example Xojo Project – and of course all the GitHub Actions Workflows.

I hope this gives you a lot of helpful hints, ideas and approaches so that you get a head start to get your Xojo Projects built using GitHub Actions Workflows.

That’s all Folks!

I hope this brief introduction of how Build Automation for Xojo built Application can be used with GitHub Actions Workflows has been helpful to some, food for thought to others.

Jürg Otter is a long term user of Xojo and working for CM Informatik AG. Their Application CMI LehrerOffice is a Xojo Design Award Winner 2018. In his leisure time Jürg provides some bits and pieces for Xojo Developers.

Primarily, we focus on the issues having the greatest impact on the Xojo community. However, that focus is not absolute. The engineering team at Xojo is using Xojo all-day, every day. They will often catch bugs in the early stages of the development of a new feature or as a side effect of fixing some other bug, long before that release gets to pre-release testers. The number of combinations of interactions between various parts of the Xojo frameworks is effectively infinite and no system can test everything. That’s why pre-release testing by actual users is so important. When you look at the bugs that are reported, 95.6% have only one user reporting them. Though we provide, in fact require, users to search Feedback before submitting a case, users often describe the same bug in varying ways resulting in duplicates. Given both the infinite number of interactions and some number of duplicate reports, the fact that overwhelming majority of reports have just one user is understandable. That we focus on the reports that have multiple users is also understandable. And of course there are exceptions, if it’s obvious that a new bug is going to effect a lot of users, we will get to work on it ASAP. In addition, if an engineer is working in a particular part of the IDE or a particular framework, since they have take the time to refamiliarize themselves with that code, they will often look for bugs that have been reported against it. 

Development tools are special because the type of people who use them are more likely to report bugs and are more likely to want to search the list of open cases, get updates about bugs and more. While it’s important to report bugs, and we can’t stress enough how much we appreciate the time and care you take in doing so, even if the bug is fixed, you still have to wait for the release in which it’s fixed. Even our engineers have to wait for bugs fixes just like you do. Still, when you run into a bug, please search Feedback first to see if it’s been reported, perhaps think of a few ways it could have been reported and do a few searches. If you find a match, add yourself to the case. If you don’t, please file a case. If you haven’t found a workaround, ask on the forum or contact us directly and we see what we can do to help.

There is a lot of automated testing that goes on before we put out a pre-release to Testers. And we will continue to add more because automated testing is a terrific and efficient way to test anything that can be automatically tested. We are always on the lookout for ways to improve efficiency in our processes.

Other IDE’s have a concept of a solution or workspace consisting of several projects, and you can leverage packages in order to share code between projects. That’s not as simple as one might think with Xojo. The Xojo Documentation «Sharing Code» explains three different ways: Copy & Paste between projects, Export/Import Items and as a last option there are External Items.

Copy & Paste is the simplest way. The downside is that after making a fix in a shared code item, it needs to be copied and pasted again and again to all projects that are using it.

Export/Import Items as well as External Items allows to save project items such as Modules or Classes in Binary or XML Format. With a Version Control System such as SVN or Git one should obviously go for XML. However, many don’t quite like the XML project format. It is readable in plain text, but not as clean and easy compared to Xojo’s Text format.

Which one would you prefer to read when looking at changes, diffs, conflicts?

• On the left: «Xojo XML project format» (*.xojo_xml_project)
• On the right: «Xojo Text project format» (*.xojo_project)

I’d definitely want to use the Xojo Text project format. And I want multiple projects that share code such as Modules with Extension Methods and various helper Methods I’ve written over the years. Business Logic Classes can be used in console, desktop and web applications – again, there’s the need to share code.

So let’s see how this can be done with MonoRepo. But what is a MonoRepo?

MonoRepo

The name consists of two parts: «Mono» (meaning: single) and «Repo» (short for: Repository). What it means: it’s a software development strategy where code for multiple projects is stored in the same repository (and therefore in the same main folder).

Advantages:

• Reuse Code: Functionality can be abstracted into shared Modules or Classes, and be included in multiple projects without the need of a package management system.
• Atomic Commits: When several projects work together, releases need to sync which versions work with each other. In a MonoRepo it’s all in one place. Once the projects are ready for an update, you can tag the current state. This will include the state of all dependent projects needed for that release. So no need to know which project in which version or state has been used in version X.
• Collaboration: Several developers can work on different projects. Shared code can be improved by all developers with the others (or other projects) benefitting, too.

Disadvantages:

• Access Control: With split repositories for each project, access to a project can be granted based upon need. A MonoRepo however allows read access to all software in the repository.
• Storage: A developer needs to check out the whole MonoRepo, even if one is working just on a single project included in the MonoRepo. Depending on the software being developed, this can be a significant amount of “not needed” storage space.

Personal Thoughts:

I like the MonoRepo setup because of Xojo’s support for cross-platform development. Everything is contained in a single repository/folder, all files are located relatively. So you cannot only move the MonoRepo folder to any location on your machine, but also to other machines – running the same or a different Operating System. Check out the Version Control Repository on your Windows working machine and start coding. Commit/Push the changes, switch to a Mac and check-out/pull the current branch you’re working on in order to do some platform specific tests. To me that’s much more convenient and efficient than Remote Debugging.

Xojo Projects Setup

Let’s see how we can set up a MonoRepo using Xojo. In this example we’re going to create two projects that share a Class and a Module. There are a few gotchas.

Setup a New MonoRepo

All we’re doing is creating a folder: «xojo-projects-monorepo». In a real world situation you’d sooner or later make a Repository out of this folder in the Version Control System of your choice.

Project One

Once I have created a new Project named «Project One» the first thing to be done in the Xojo IDE is:

• Add a new project item: Folder
• Name the folder according to the project, but in a way that is best represented on disk as a folder: «project_one»
• Move all project items (App, Window1, MainMenuBar) in this folder

That should look like this:

Then let’s save this project as a «Xojo Project» (*.xojo_project) to the «MonoRepo folder»:

What do we get to see?

• Project_One.xojo_uistate: That’s the state configuration of the IDE when this project has been saved. In a VCS you can ignore the files «*.xojo_uistate» safely.
• Build Automation.xojo_code: we’ll come back to that later.
• Project_One.xojo_project: The main project file, containing the references to all included project items, which are stored as individual files.
• Project_One.xojo_resources: This is a binary file containing the AppIcon, and similar resources.
• Folder «project_one»: The folder we’ve just created. In there you’ll find the files of the project items you’ve moved in there: App.xojo_code, MainMenuBar.xojo_menu and Window1.xojo_window

Project Two

Let’s make this short. We’re doing the very same steps again, just for a «Project Two», with all project items in a folder «project_two».

Our MonoRepo now looks like this:

So far, this is simple and clean. The main project files are in the root folder, all project related items are in their own project folder.

But hey – just one «Build Automation»? Yup… That’s a bit unfortunate. We’ll come back to that later.

Shared Code

Now for the more interesting part. Let’s create a Class and a Module that we want to share in both Projects.

In Project One

• add a new folder: «shared_code»
• add a Module containing a Constant to the shared code folder: «MyModule»
• add a Class containing a Method to the shared code folder: «MyClass»
• Save the Xojo Project.

The shared code folder and the to-be-shared project items are now saved as individual files/folders to disk:

Add Shared Code to Project Two

We now want to add this shared code to «Project Two».

On Windows you can do this using drag and drop: Drag the folder «shared_code» from Windows Explorer into the Navigator (left pane) of the Xojo IDE in «Project Two».

On macOS however, this will not work as expected. Due to a bug the project file will be corrupted since it’s saving wrong locations. To show you: I’ve done this and opened the «Project_Two.xojo_project» in a Text Editor:

Oops… MyClass and MyModule have a weird location: ../../../

As a result, the project won’t load correctly.

That’s why I recommend the following steps:

• Add any new folders manually in the Xojo IDE: In «Project Two»: Insert Folder «project_two» (name it exactly the same as already existing on disk!).
• Open «Project One», select and right-click to copy the project items «MyClass» and «MyModule»
• Back in «Project Two»: paste the project items in the previously created folder “shared_code”
• Close «Project One» again, to have only a single project opened

That’s what it should look like – the shared project items are being referenced properly, relative to the root folder of the MonoRepo:

So that’s it. We now have «MyClass» and «MyModule» available in both Projects. And since they are effectively the same files on disk, they’re shared between them. So from now on any code change will be reflected and used by both projects.

You’ll only need to do these steps once for a new project item that you’re going to share between projects. Once they are referenced in the project files, they’ll point to the same file for all projects. That’s possible because the project file is in the root of the MonoRepo, and all project items added are being referenced relative to that root folder.

So it doesn’t matter where the main folder is located – and the structure works fine for all Operating Systems you can use to code with the Xojo IDE.

Let’s Code

Finally make use of this and use the shared code in the projects:

While your projects are evolving you can add more shared Classes, Modules, Methods, Constants, Images, and add them to the other projects in the MonoRepo as explained above.

Enjoy the benefits of your MonoRepo and reusable code!

Watch Out

Be aware that the Xojo IDE isn’t designed for shared code. It doesn’t look at your MonoRepo as a «solution of several projects». It’s not aware of changes happening outside of an already loaded/opened Project.

That’s why I recommend to only have one project open at a time, and only open a second project to copy and paste new project items to the other project.

Why? Well, let’s assume you have both projects opened. You’re making a change to «MyClass» in «Project One» and save. Since the Xojo IDE with the opened «Project Two» is not aware of this change you still have the previous state loaded in Memory. And chances are that once you’re saving «Project Two» you’re going to overwrite the file with the state that «Project Two» currently has, therefore loosing the changes made to «MyClass» in «Project One».

One workaround might be: Frequently save the project after each change. Never switch to another project if not saved. If a second opened project needs that change, switch to it and «Revert to saved». You can do this by simply (un)checking a Build Target to make the project «dirty», so that this Menu Item gets enabled. Then «revert to saved» (without saving changes).

But honestly, it’s too risky in my opinion. That’s why I try to only work on a single project at any given time. As always … the exception proves the rule

File Type Groups

If your application uses files with app specific icons, you’re going to create a File Type Group. In a MonoRepo you need to be aware of how Xojo is saving this. Let’s have a look at an example:

I have created a «File Type Group» named MyFileTypeGroup and saved it to the shared_code folder. Has this been a good idea?

• MyFileTypeGroup.xojo_filetypeset: This is a text file containing information about the custom file type. So far so good, but… where is the assigned Icon?
  If you have a close look at the contents of this file you’ll notice that it references: Project_Two.xojo_resources
• Do you remember… we’ve noticed this file and described it like this: Project_Two.xojo_resources: This is a binary file containing the AppIcon, and similar resources.
  So it contains binary information for both AppIcon’s, as well as FileType Icons.

Back to the question – has it been a good idea to save it to a shared code folder?

I don’t think so… Well, it works – even if you add it to a second project. However, when saving the project it will always reference the currently opened project, and save the binary representation of the Icon again to another .xojo_resources file. This leads to unwanted changes to both files.

So don’t do that… Always and only save a «File Type Group» per project. Even if this means an unwanted duplication of a project item that you need in several projects.

I just accept that inconvenience – knowing I’m using Xojo and the «Text Project format» in a way that it has not been designed for. All the other benefits are worth it.

Build Automation

Do you remember that we wanted to have a look at that later, when we’ve noticed that there is only a single «Build Automation.xojo_code» file in our MonoRepo?

Build Automation will be shared between all projects since you can’t move that to another place. It’ll always be next to the project file. For our MonoRepo this means: it will be the very same for all projects since we have all projects files in the root repository folder.

What can we do to still have Build Automation «per project»? We need a way to distinguish the projects in IDE- and Build Scripts. What has worked fine for us is to use the «Build Setting: Windows – Internal Name» and set it to an (internal) project name:

Pre/Post Build Scripts

For the Build Steps «Scripts» and «External Scripts» we then need to first add check if we want to run it for the currently to-be-built project:

if (PropertyValue("App.InternalName") <> "project_one") then return

This is the workaround for this limitation of the Xojo IDE to not have Build Automation «per project» if there are several projects in the same folder (which happens to be the case in our «MonoRepo»). You’ll see all Scripts in all projects. And since the Xojo IDE will run them all we need to make sure to bail out if it’s a script for another project.

Having said that, it’s also a good thing! This obviously also allows you to share Build Scripts between some or even all your projects.

This ScreenShot shows an example of a Script that’s intended to run only for «Project One»:

Copy Files Steps

No good news here… there are currently no options to check a «per project» value if a Copy File step should be executed or not. It’s a «for all projects» or nothing.

The workaround is to copy additional files using a Post Build Script. And if you’re using the Xojo IDE on all supported OS (Windows, macOS, Linux), then you can leverage conditionals depending on the OS the XOJO IDE is currently running and building in the Scripts, too!

The files to be copied can be stored in a String Array. To know where to copy from (relative to the MonoRepo’s location, so it doesn’t matter to where a Developers checks out the repository):

if TargetWindows then
  sFolderResources = "%PROJECT_PATH%\resources"
elseif TargetMacOS or TargetLinux then
  sFolderResources = "$PROJECT_PATH/resources"
end if

Where to copy the files to?

Dim sAppBuildPath As String
if TargetWindows then
  sAppBuildPath = CurrentBuildLocation
elseif TargetMacOS or TargetLinux then
  sAppBuildPath = ReplaceAll(CurrentBuildLocation, "\", "") 'don't escape Path
end if

This example will use the proper Shell Commands on both Windows or macOS/Linux to copy the list of files:

Dim i As Integer = sCopyFiles.Ubound
while (i > -1)
  if TargetWindows then
    call DoShellCommand("copy """ + sCopyFiles(i) + """ """ + sCopyToFolder + """ /y /v", 0)
  elseif TargetMacOS or TargetLinux then
    call DoShellCommand("cp -f """ + sCopyFiles(i) + """ """ + sCopyToFolder + """", 0)
  end if
  i = i - 1
wend

Adding a Third Project

Before you’re going to add a new project: Make sure you have committed all changes of the MonoRepo in your Version Control System.

If you then create a new project, and do the same steps as described above (move all project items into a new folder «project_three») and save the project to the root folder of the MonoRepo – what do you guess will happen?

The new project related files are there in the root and in the created folder «project_three». That’s expected. However, you’ll notice that the Build Automation files have been overwritten. That’s unfortunate – but expected, too. It boils down to the fact that the Xojo IDE with your newly created project is not aware of whatever you have put in Build Automation before. So it’s going to save the blank Build Automation, since that’s the state of the opened IDE.

Don’t worry, just quit the Xojo IDE, then revert the changes to Build Automation in your Version Control System. Reopen the project, and it will now pick up the previous state which you’ve just reverted. Now it’s possible to add more build steps for the third project.

Similar issues might happen if you’re then going to copy-paste shared code items e.g. from «project_one» to the newly added «project_three». After you save, your Version Control system might show a ton of changes in the shared code, e.g. properties being saved as “True” when before they’ve been saved without quotes. So I usually do the same procedure: revert the (unnecessary/unwanted) changes in the shared code items after a copy-paste and save to a new project. That’s fine since there have been no “real” changes to those files. All that’s important is that the files are being linked properly in the main project file of «project_three».

Everything Else

I don’t intend to explain advanced possibilities here. Just two situations you might encounter:

A Method in a shared Module contains Desktop stuff, but you want the rest of the Module to be used in a Console app, too. You can do this using «Conditional Compilation», e.g. in Code or by selecting a Target («Include in») for a Class/Method in Inspector.

You want or need to build different projects with different Xojo Versions. That might be because of a legacy project. Or that you continue to build for TargetWindows with an older Xojo Version while building for macOS with the newest Xojo Version. Then I’d suggest to code using the lowest used Xojo Version. Add functionality available only in newer Xojo Versions using Conditional Compilation:

#If XojoVersion >= 2021.01 Then 

you can even leverage newer Event Handlers (that are only available in newer Xojo Versions) in there using AddHandler. We’ve done that for example with DarkMode Support for our macOS builds (while the productive Windows builds are still being built with older versions).

About Our MonoRepo

Our main MonoRepo currently has 12 projects written in Xojo. It’s a mix of Desktop and Console applications, Commercial and Internal apps. They’re being worked on by multiple developers, allowing us to code or debug by running the Xojo IDE in different OS environments with ease.

We’ve been successfully using this approach for more than 14 years with REALbasic, REAL Studio and Xojo, always with their Text Project format.

We have structured our MonoRepo more or less like this:

• /
/project_A
/project_B
  Such as you have seen above: All Project files, and the shared BuildAutomation in the root folder. And every project has its own project folder.
• /shared
  The common folder is being used in all our projects, no matter if the project effectively needs every bit in there at its current development stage. It’s kind of our own addition to the Xojo Framework that we can rely on in all our projects.
• /shared/controls
  We’ve subclasses every Control (to have extended functionality, fixes and workarounds) and only use subclassed Controls in all our projects.
• /shared/classes
/shared/functions
/shared/resources
  Same story here. Over the years we’ve written many Modules with custom Extensions to Xojo Framework Classes, additional/custom String/XML/JSON functionality, abstracted the encryption related functionality we need, and we have a set of own data structures/types that are not available in the Xojo Framework. And there are some resources we use in about every project, such as the company logo or Toolbar Icons.
• /components
/components/reporting
/components/webservice
  These components are being used in some, but not all projects. Important here is that they need to be functional on their own, without dependencies to app/project related code. Examples known in the Xojo community are e.g. the reporting engine Shorts, or Aloe for WebServices.
• /build
/build/configuration
/build/processing
  Last but not least, in that folder we have all (post) build related functionality. That’s per-project build settings (being read and used by the post build scripts – and yes, you’re right, this could be put into the individual project’s folders), but also our shared post build processing (again kicked off by post build scripts) which deploy all our builds (Alphas/Betas/Final versions) internally and upload it to our app-update WebServices.
  I can only recommend to have such (post) build-related stuff under version control! Be it for an emergency fix for an old version (while the build process/configuration of your current version has changed significantly), or to work in a feature branch on new functionality that requires changes to the build processing (without affecting the productive flow).

That’s All Folks!

I hope this brief introduction of how one can share code between different Xojo Projects using a MonoRepo has been helpful to some, food for thought to others.

Jürg Otter is a long term user of Xojo and working for CM Informatik AG. Their Application LehrerOffice is a Xojo Design Award Winner 2018. In his leisure time Jürg provides some bits and pieces for Xojo Developers.

If you haven’t heard of Docker, go ahead and read their excellent Documentation: Docker – Overview.

I’m just going to quote some basics from the Overview to give a brief introduction of Docker, Docker image and Docker container:

Docker is an open platform for developing, shipping, and running applications. It provides the ability to package and run an application in a loosely isolated environment called a container. The isolation and security allow you to run many containers simultaneously on a given host. Containers are lightweight and contain everything needed to run the application, so you do not need to rely on what is currently installed on the host. You can easily share containers while you work, and be sure that everyone you share with gets the same container that works in the same way.

A Docker image is a read-only template with instructions for creating a Docker container. Often, an image is based on another image, with some additional customization. To build your own image, you create a Dockerfile with a simple syntax for defining the steps needed to create the image and run it.

A Docker container is a runnable instance of an image. You can create, start, stop, move, or delete a container. By default, a container is relatively well isolated from other containers and its host machine. You can control how isolated a container’s network, storage, or other underlying subsystems are from other containers or from the host machine. A container is defined by its image as well as any configuration options you provide to it when you create or start it.

A Docker Registry is a stateless, highly scalable server side application that stores and lets you distribute Docker images.

Why use Docker with a Xojo Web App?

You can package your Xojo Web Apps in a Docker Image. That allows you to run an instance of your applications easily in a Docker Container. Docker provides the infrastructure to host the apps, start/stop them, switch between image versions – and much more.

The Docker Images containing your Xojo Web Apps can be copied to other machines. This might be some Linux or macOS machine (Windows seems to be a bit more tricky), a Cloud Service – or even a Synology NAS. You then can import the Images on the Docker environment of those machines, and serve your apps from there.

If you’re pushing the Docker Images to a Registry (e.g. Docker Hub), it gets even more convenient. Docker Hub is a service provided by Docker for finding and sharing container images with your team or the public. So you’ll build the Docker Image with your Xojo Web App, push it to the Registry. After that, you (or your team, or everyone) can just pull the Images to their Docker infrastructure and run them in a Container.

How to build a Docker Image containing a Xojo Web App?

One could answer obviously: it depends. But let me try to explain the basic required steps. For this example we’re going to use a macOS machine to build the Xojo Web App and Docker Image. Then we’ll deploy and run a Docker Container on the local developer machine and on a Synology NAS.

Requirements

• Xojo with a license allowing you to build a Xojo Web App for Target Linux (Intel, 64Bit).

Docker Desktop installed on the macOS developer machine. Download and install it from here: Docker for macOS. After that you should have the Docker GUI up and running. And in Terminal.app you should have the command line tools available. You can double check this by entering this command:

docker version

• We’re going to build a Docker Image based on Ubuntu (Linux). To run a Docker Container with this image, we obviously need a machine supporting this. Both macOS and the Synology NAS will work just fine.

Are you ready and set up? So let’s go and try this.

Build a Xojo Web App

Open a Xojo Project with a Web Application. I’m going to use a CRC Calculator I’ve written. Debug-Run it locally to make sure the Web App works as expected.

Once we’re ready to build we should think of what we’re going to need for the Docker Image. Check the following properties in your Xojo Project:

• The most obvious one: Tick the “Build Target: Linux, x86-64Bit”. Since our Docker Image will run Ubuntu / Linux-64Bit, we need the Xojo Web App to run in such an environment.

• Then in “Build Settings – Shared”, set the “Build – Port: 80“. In fact it doesn’t really matter which Port you’re choosing. All that is important for now is that you know which one it is.

• That’s about all we need to do within the Xojo IDE – so let’s hit “Build”.

We now have the built Web App ready. Next step is to package it in a Docker Image.

Dockerfile

Open the Web App’s Build Folder in Finder. Next we need to write the instructions to get it in a Docker Image. Open your favourite Text Editor. Create a Text-File with Filename: Dockerfile (no file extension). Save it in the Build folder (next to the application’s executable file). The Content we’re saving in Dockerfile is:

#BASE IMAGE
FROM ubuntu:20.04

#INSTALL REQUIRED LIBRARIES
ENV DEBIAN_FRONTEND noninteractive
RUN apt-get update && apt-get install -y libunwind8 libglib2.0

#ADD APPLICATION TO DOCKER IMAGE
ADD / /app/

#EXPOSE PORT AND RUN APPLICATION
EXPOSE 80
WORKDIR /app
CMD /app/CRCCalculatorWeb

This describes how Docker is going to create the Docker Image. Let’s briefly explain the steps of this Dockerfile:

• We’re going to use Ubuntu 20.04 as a base image. That about the same as saying: “Let’s set up an environment running Ubuntu 20.04 first.”

• We then set an environment variable allowing to install updates without user interaction. Then the system gets updated, and required Libraries installed (libunwind8, libglib2.0).

• The whole Content of the Build Folder (or in other words: everything next to the Dockerfile – that’s basically our Xojo Web App) is being copied into the image to the location /app

• Expose 80: Do you remember? That’s the “Build Port” we’ve set in the Xojo IDE. So this tells that when running this Image as a Container Instance later we can attach to this “virtual port”. It doesn’t matter if several applications in different Images/Containers use the same port. That’s because when running an Instance, we can later configure the running Instance to map the Ports, e.g.: “8088 (external) -> 80 (internal)”. So a second Web App Instance or App could use e.g.”8089 (external) -> 80 (internal)”. That’s why for our own convenience we can use Port 80 for every of our Xojo Web Apps’s Docker Image.

• Finally, the instructions tell where the working directory is, and with the last command the Xojo Web App is being launched.

Alright – everything is ready so that we can now create the Docker Image.

Docker Image

Open Terminal.app and change directory to the Build Folder of the Web App:

cd /path/to/your/xojo-webapp-project/Builds\ -\ CRCCalculatorWeb/Linux\ 64\ bit/CRCCalculatorWeb

You’re now in the folder with the Dockerfile and your Web App.

A Docker Image always needs a Tag. Such a Tag looks like this:

jotools/crccalculator:1.0.0-dev

The parts are: (company-name)/(product-name):(version-label-tag)

So… let’s build the Docker Image – enter this in Terminal:

docker build -t jotools/crccalculator:1.0.0-dev .

What this does is: Build a Docker Image with Tag ___ from “this current directory” (the dot at the end).

Side-Note: If you’re re-building an Image with the same Tag of an already existing Image, it gets overwritten. You could also first remove an existing image like this:

docker image rm jotools/crccalculator:1.0.0-dev

You can now launch the Docker Desktop .app and find your Image there:

If you prefer to see the image using the command line:

docker image ls

Run Docker Container

Let’s now take the Image and run a new Docker Container using that Image. We will configure the Docker Container Instance to use the local Port 8088. In Docker Desktop GUI:

• Select the Image, click on the Button “Run”

• Expand the optional settings, enter a Container Name of your choice and Map the “LocalPort: 8088” to “Container Port: 80”

• Then… click on “Run”

And that’s it – we have the Container up and running:

If you prefer the command line:

docker run -d --publish=8088:80 --name crccalculator jotools/crccalculator:1.0.0-dev

Let’s access our Xojo built Web App running in the local Docker Container using Safari:

Side-Note: If you just want to try this example project then you can pull the image like this in Terminal.app:

docker pull jotools/crccalculator:1.0.0

Export Docker Image

The easiest way is to push the Image to a Registry such as Docker Hub. That obviously requires a registration – so we won’t cover this here and now.

Let’s export the Image using Terminal.app.

You should still be in the Build – directory of the Xojo Web App. If not, change to that folder.

Then export the Docker Image to a file like this:

docker save jotools/crccalculator:1.0.0-dev | gzip > ./CRCCalculatorWeb.dockerimage.tgz

This command is saving the Image/Tag to a .tgz located in the current directory.

Run Docker Image on a Synology NAS

If you have a Synology NAS supporting Docker – this is how you can run the exported Image on your NAS:

• First of course: Install the Synology Docker Package

• Copy the exported CRCCalculatorWeb.dockerimage.tgz to a Share on the NAS

• Launch the Docker .app on the NAS

• Under “Images”: Add -> From File -> (choose your CRCCalculatorWeb.dockerimage.tgz)

• Select the imported Image, click on “Run”

• Enter a Containername of your choice:

• Click the Button “Advanced Settings”: Same story here – Map the Local<->Container Port. In this example: Local 8099 <-> Container 80

• Finish the assistant. The Container should now be up and running:

Let’s access our Xojo built Web App running in the Docker Container of the Synology NAS using Safari:

What next?

There are a lot of features and possibilities which we won’t cover here. Let’s just pick a couple and briefly explain without going into detail. You’ll find excellent documentation on Docker’s Website if you want or need to dig in further.

Docker and Persisted Storage

Note that this example has no persisted storage. Which means that you can save files within a Container – but once you stop or remove the Container (e.g. to run a new Container with a newer Image version) the created data is gone. That’s a good thing – as a Container will always behave the same when deployed, not being cluttered with data that has come from somewhere.

If your Web App requires to store data on the filesystem you should add a Volume. In the Dockerfile add a line like this:

VOLUME /data

You then can have your WebApp save data to the folder /data.

If you run a Container from such an Image – have a look at the Advanced Settings. Since the Image exposes a Volume, you can choose a local folder (on the machine where Docker is serving the Container) to be attached to /data. Same story on the Synology NAS.

Once you remove the Docker Container, the Data will still be there. So you can run another Container (e.g. with a newer version of your app), attach the same/existing data-folder. That way you can continue and keep existing data.

Environment Variables

Especially if you’re going to Deploy the Docker Image on various environments, you might want some “settings”. One approach is to use Environment Variables in the Dockerfile:

ENV MY_CUSTOM_SETTING=4430

Again in the Advanced options when running a Container you can override these Environment Variables to fit your needs.

Build Automation

If you’re building regularly and don’t want to enter commands in the command line after every build you could think about a Post Build Script which builds the Docker Image and optionally even pushes it to a Registry (e.g. Docker Hub).

An example is available here: Example Project – Xojo Web App 2 Docker

Docker Registry

The easiest way is to distribute a local Docker Image is to use a Registry such as Docker Hub. That obviously requires a registration and your Docker Client to be signed in. You can then push the Docker Image to the Registry, and pull it from there on the Docker Clients.

docker push jotools/crccalculator:1.0.0-dev

docker pull jotools/crccalculator:1.0.0-dev

Restart policy

In order to automatically launch a Docker Container after a reboot (of the host machine; of the Docker daemon): see Docker’s Restart Policy Documentation. 

This command changes the restart policy for an already running container named crccalculator:

docker update --restart unless-stopped crccalculator

And this command will ensure all currently running containers will be restarted unless stopped:

docker update --restart unless-stopped $(docker ps -q)

That’s all Folks!

I hope this brief introduction of how a Xojo built Web Application can be used with Docker has been helpful to some, food for thought to others.

I wish you all the best and I’m curious if the Xojo Forum will get new posts in the near future with Docker Hub Links to interesting Xojo Web Apps which you do provide to the community.

Jürg Otter is a long term user of Xojo and working for CM Informatik AG. Their Application CMI LehrerOffice is a Xojo Design Award Winner 2018. In his leisure time Jürg provides some bits and pieces for Xojo Developers.