learn | unlearn | relearn

With Xojo Web 2, it becomes relatively easy to set up a Server and run your first App. You would not even need an own webserver as a Xojo Web 2 App has built-in its own. But in today's world, running a Webapp is one thing; running it securely a different story. This beginner's guide aims to enable you to run your first App in no time.

What we will achieve in this tutorial:

  1. Building a Linux Server from scratch (Ubuntu 20.04 LTS)
  2. Connecting your domain to the server
  3. Installing all prerequisites for Xojo Web App on the Ubuntu  Linux Server
  4. Installing a postgreSQL DB (for future use)
  5. Installing your Xojo Web App
  6. Automation of  the server as such that your app will restart automatically in case it quits for whatsoever reason.

Building our own Linux Server

There are many ways how you can set up your own server. I'm using upcloud.com for this tutorial, but it pretty much works the same way with digitalocean.com. I'm a fan of upcloud.com, as there IaaS is very fast, especially for their storage:

DigitalOcean alternative - Compare UpCloud with DigitalOcean
UpCloud is a great alternative to DigitalOcean with a faster and more scalable cloud, Linux and Windows support, and 11 global locations.

Creating our first server

Account first! Of course you have to register at upcloud.com I leave you alone with this task. Once you are logged in, we can now create our first own server:

I'm chosing a server in The Netherlands for no particular reason.

I'm chosing the cheapest plan.

I do rename the storage to something which I'll better recognize in future, because you can later attach this storage to a different server, so I want to remember what this storage in indent to be used for.

For the server I'm using an Ubuntu Server 20.04 LTS. A version with Long Time Support is the right approach, as we want in future to concentrate on Xojo development and not become the next Linux superstar.

Now it is time to open your public key in a text editor. If you can't remember this the key (with  the extension .pub, which we created in the following tutorial:

How To Build an SSH Connection from macOS to Linux?
How does this headline relate to Xojo? Well, there are many reasons why it is cool having the possibility to connectremotely to another server. You’ll need such an option for a secure connectionto your remote server to upload files and make changes on your server. Butperhaps you are running a r…
I'm naming the key Xojo but you can of course name it differently

Your screen should now look like this:

I recommend that you change the hostname to something short but descriptive. Upcloud will pass this value over to Ubuntu during the installation, so you will regret it later to use special characters in this name and to make it very long.

Okay, here we go. Now hit "Deploy" and let upcloud.com do the magic!

22 seconds in my case to not only deploy the server, but to actually start it. Impressive, isn't it?

In the overview we can see the IP upcloud.com addressed to our new instance.

In my case it is: 94.237.41.19 (in the rest of this tutorial, you will of course have to replace my IP by yours!). Sounds silly, but you can easily forget this.

Now let's launch our terminal window and start with the real fun! The user is of course root and we are now typing:

ssh root@94.237.41.19

The server will ask you to accept the fingerprint (this is only asked once, per client you are trying to connect). Just confirm with yes.

But hold on, why is my server asking for a password. We did create an SSH key to avoid this, right? Well in the case you only have created one SSH key, you will probably already be connected. If you have multiple keys on your system (like I do), you have to specify which key to use.

Let's do the following in a new(!) terminal window:

ssh -i xojo root@94.237.41.19

Et volià, either way you will now be connected!

Congratulations! Well done so far.

Connecting your domain to the server

Now it is a good moment to connect a domain to your server. Good moment, because this can take sometime in case you buying a new domain. I am just using a subdomain for this purpose:

Subdomains are creater fast, as the DNS Servers already know the root domain.

Now you need to point the A/AAAA record to your new IP. In my case to IP 94.237.41.19. Your final result should somehow look like this.

Let's try to connect now:

Big drama! What is happening now? Well the permission are wrong. A simple correction will solve this issue:

chmod 400 ~/.ssh/xojo
chmod 400 ~/.ssh/xojo.pub
chmod 755 ~/.ssh

If you are running a macOS higher than 10.12.2, it might again not work once you closed your terminal window and you are trying the connection again. In this case you have to do the following:

ssh-add ~/.ssh/xojo

You can check with

ssh-add -l 

if your key was successfully added to your ssh agent. In my case everything is working now. This kind of issues are due to Apple changing the OpenSSH implementation all the time.

Technical Note TN2449: OpenSSH updates in macOS 10.12.2
TN2449: describes changes to OpenSSH in macOS 10.12.2.

Again, most users will only have one certificate and will the not run into the above issues, and they can connect directly via

ssh root@testapp.yourdomain.com

Ok, now that we have our Linux machine and connect as root via our certificate and via our domain to the server, let's party and install all our prerequisites for Xojo Web App 2.

Installing all prerequisites for Xojo Web App on our Ubuntu  Linux Server

What ever you are planning to do now, you probably saw already that there are outstanding updates, please do nothing but the following. Create a new user(!) and don't even think of continuing to work with root!

sudo useradd -s /bin/bash -d /home/xojo/ -m -G sudo xojo
sudo passwd xojo

The above commands wil create as user xojo, give it sudo permission and define a password for our new user xojo.

Now we need to copy the public part of our key (xojo.pub) to the home folder of our new user "xojo".

sudo mkdir /home/xojo/.ssh
sudo chmod 0700 /home/xojo/.ssh/
sudo -- sh -c "echo 'YOUR FULL PUBLIC KEY!' > /home/xojo/.ssh/authorized_keys"
sudo chown -R xojo:xojo /home/xojo/.ssh/

Now you need an "editor". You can use whatever you want. I'm using vim (which is installed already). If this is not the case, just install it with:

sudo apt-get install vim

I know "sudo" is obsolete, as we are still working as root, but let's change this now:

With your editor of choice, change the following file:

sudo vi /etc/ssh/sshd_config

Ensure that the following settings are changed in the file:

PermitRootLogin no
PasswordAuthentication no
PermitEmptyPasswords no
PubkeyAuthentication yes
ChallengeResponseAuthentication no
UsePAM yes

Don't forget to uncomment (delete the # sign) left to PubkeyAuthentication!

If you are sure that everything is right, restart the SSH-Server, exit, pray, and try to re-connect.

sudo service ssh restart

Now you can connect to your server via

ssh xojo@yourdomain

Any access via passwords, or root@yourdomain is now blocked!

Now I have some good news for you. If you have made it to this point, you have achieved the most difficult part! It might happen that you are locking yourself out of the system, if you are making mistakes in the above changes. In the worst case, just delete your server, and remember that it took you only a few seconds to create a new one!

So now that we entered the party, let's have some real fun.

First of all we should now update our system. Don't forget the sudo prefix from now on, as otherwise you will be a nobody, without the necessary permissions!

sudo apt update && sudo apt upgrade

And now let's install a few  packages:

  • nginx - a webserver, which we will use as reverse proxy to combine the outside world with the xojo web app
  • postgresql - a database, for future use
  • fail2ban - that's a naughty little tool, blocking the system if there are too many wrong logins (should not happen to you now, as you are using a certficate). If it happens, you will be blocked for one hour (unless you are rebooting the machine). I wrote an own article on how to configure fail2ban.
  • ufw - a simple, but effective firewall
sudo apt install nginx postgresql postgresql-contrib fail2ban ufw

and 1 more tool:

sudo apt install certbot python3-certbot-nginx

If you are an American, you are done now. But we you speak more languages, you most likely want to install your locale as well - for instance in Germany you would do the following:

sudo locale-gen "de_DE.UTF-8"

After all these updates, it is now a good moment to do something you normally don't need to do on linux, rebooting the system:

sudo shutdown -r 0

Setting up postgreSQL

First we are creating a user:

sudo -u postgres createuser --interactive

As a postgres user needs to have its own database, let's create that one as well

sudo -u postgres createdb xojo

Now our local connection to postgres with the postgres user xojo should work

sudo -u xojo psql

It does for me, lucky me.

Now, we will create a database called "xojodb".

CREATE DATABASE "xojodb" WITH OWNER "xojo" ENCODING 'UTF8' TEMPLATE template0;

As we are the future rocking Xojo stars, let's grant us full access:

GRANT ALL PRIVILEGES ON DATABASE xojodb TO xojo;

with

\l

We can now list our databases:

use

\q

to quit postgres. Done!

Setting up our firewall

By the way: you remember that we installed fail2ban. You can search on the internt for fine-tuning, but there is really nothing special we need to about it, other than installing it. It will activate itself automatically during the installation. It was even written there, but who is reading stuff like that.

sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https

Installing a Webpage

I personally like to first check if a normal webpage will work, before I'm playing around with Xojo Web 2 (or any other tool / app).  Ubuntu likes to see webpages under /var/www/html/ . So let's create there a home for our future first Xojo Web App 2:

sudo mkdir /var/www/html/xojo
sudo chmod 755 -R /var/www/html/xojo
sudo chown xojo:xojo -R /var/www/html/xojo

On a side note, latest after your reboot, your webserver should already work and it will show you the standard page of Nginx under your linked domain. So in my case, testapp.xojodocs.com is currently showing this:

Now we need to tell nginx, that it should look in our new folder, rather than in the root of /var/www/html/

Of course I can not explain all details of Nginx in this article, so trust me that we first have to create a config file for our xojo domain, in my case: testapp.xojodocs.com:

sudo vi /etc/nginx/sites-available/xojo

You can use any other editor you like. It is only important to create exactly that file mentioned above and (!) to copy the following content into it:

server {
        listen 80;
        listen [::]:80;

        root /var/www/html/xojo;
        index index.html;

        server_name testapp.xojodocs.com;

        location / {
                try_files $uri $uri/ =404;
        }
}

Please note: as with SQL it is important in Nginx configuration files to end each line with a semi-colon;

So what is the above doing? It is basically telling Nginx to listen on port 80 for any connection claiming to be testapp.xojodocs.com and to forward this request to the the folder /var/www/html/xojo. The first file to automatically open is index.html. If that file or the folder doesn't exist ... big drama, raise an error 404.

Now, we actually have a big drama, as we are missing an index.html file. So let's do this right now:

sudo vi /var/www/html/xojo/index.html

Type the following content into the file and save it:

you can use of course any other content, it doesn't matter what.

Now we need to enable our xojo section in Nginx, this is done with a symbolic link, and only needs to be done once (as it is a symbolic link):

sudo ln -s /etc/nginx/sites-available/xojo /etc/nginx/sites-enabled/

And now we need to restart our Nginx service, but let's test it before. This is done via:

sudo nginx -t

If you see the following, than you are good to restart your server, otherwise have a nap and look for your mistake(s):

Restarting the Nginx server:

sudo /etc/init.d/nginx restart

Now let's check in our webbrowser what testapp.xojodocs.com is showing:

Okay, no surprise here: it is an insecure side, it looks awful (as we don't use any HTML in our index.html file) but it is working! Well done!

You might be wondering, why I've chosen to first install a "normal" page. Well we will now add a secure certificate and this is very simple, as long as you have a simple configuration file. All we need to do is:

sudo certbot --nginx -d testapp.xojodocs.com

Answer all the questions as you want but ensure to chose '2' on the last one:

Now we need to restart our Nginx server and look at the results:

sudo /etc/init.d/nginx restart

Et voilà, caramba, we have a secure webpage:

Notice the lock symbol. We have a SSL protected webpage

SFTP

For getting our app on the server, we need a transfer program. I can recommend Transmit, but any other app will work as well. The charme of connecting via certificates is that it's now a breeze to connect securely such a program oo. No need to install an SFTP server etc. all you need to do is configure the Transmit app.

That was easy, wasn't it?

Deploying the Xojo Test App

Xojo is offering a test Xojo Web App, so that you don't need to buy a license, if you do not know yet, if you will ever be able to maintain it:

http://docs.xojo.com/UserGuide:Web_App_Deployment_Overview

Please ensure to download the 64-bit version and please note that it is compiled to use the port 8080.

http://cdn.xojo.com/Documentation/TestWebApp/StandaloneDeploy64bit.zip

If you are compiling your own apps (means that you are already a customer), you can specifiy your own port, for instance 9001.

Now let's unzip the package and upload all files to our remote xojo folder under /var/www/html/xojo:

To be clear the files marked in blue (or any other color, in case you are colorblind) need to be moved!

This will take longer than setting up the whole Linux server, but let's not got into that :-). Let's not get off-topic, by the end of the day or whatsoever it should look like this:

Okay, now we need to get rid of the index.html (there it goes our beautiful webpage), as we are now ready for the Xojo Web App World (well close to it):

sudo rm /var/www/html/xojo/index.html

I'm sure that you now eagerly tried a refresh of your webpage. As this didn't work, you restarted Nginx, but it is still not working. So let's continue:

First of all we need to make the main File executable:

sudo chmod 755 /var/www/html/xojo/XojoTest

Now change your directory into this folder:

cd /var/www/html/xojo/

And execute from that location(!!) the app in your terminal:

./XojoTest

Hurray! If everything went OK, you will see an running app in your terminal

Depending on the browser you are using, you might see, or you might not see your app under http://testapp.xojodocs.com:8080 . Usually Safari is working, all the other browsers not.

Please remember again that you have to replace testapp.xojodocs.com by your domain! Everywhere in this tutorial!

We are close to victory! Bare with me.

Finetuning Nginx

Now back to Nginx. Remember that I said that we are using Nginx as a reverse proxy. One reason (of many) is that you don't want to give your customers a URL with a port number, right? So Nginx should do this for us. So let's go back to our Nginx configuration file:

sudo vi /etc/nginx/sites-available/xojo

Oh, you can't type, because your Xojo Web App is still running. You can use <control> and the letter 'c' to stop your app.

Now you have to be very careful to replace the right stuff.

This paragraph:

location / 
{
   try_files $uri $uri/ =404;
}

needs to be replaced by:

location / 
{
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   proxy_set_header X-Forwarded-Proto $scheme;
   proxy_set_header X-Real-IP $remote_addr;
   proxy_set_header Host $http_host;
   proxy_pass http://127.0.0.1:8080;

}

Note the last line. This Xojo App is compiled for port 8080. You need to replace in future this port whatsoever, if you have compiled your app to use a different port! Please don't forget that little "detail". NEVER!

This little change is bascially telling Nginx that it should pick up any request coming via our domain and to forward it to the Xojo Web App Server listening on 127.0.0.1 (which is the localhost) listening on port 8080.

Ok, now let's restart Nginx, go into our xojo folder and restart our app:

sudo /etc/init.d/nginx restart
./XojoTest

Now go to your browser and type in your domainname (without a portnumber!) and enjoy the most beautful Xojo Web 2 Test App ever! :-)

You made it! Congratulations.

Automation

Unfortunately you won't be happy very long. Trust me! If you will reboot your server, or close the running app, or the running app won't run any longer ... you will not be happy either.

The easiest way to ensure your app will always run, is to install it as service. Now services sound very complicated if you think of Windows Services for instance, but acutally on Linux they are extremly straightforward. Stay with me for the last mile on our long walk.

Let's create the following service:

sudo vi /etc/systemd/system/XojoTestApp.service

Enter the following and save this file

[Service]
Type=simple
Restart=always
RestartSec=3
User=xojo
ExecStart=/var/www/html/xojo/XojoTest --secureport=443

[Install]
WantedBy=multi-user.target

Okay, that's it, you just create a service! Now we need to enable it. This is done by the following command:

sudo systemctl enable XojoTestApp.service
sudo systemctl start XojoTestApp.service
sudo systemctl status XojoTestApp.service

You should now see somthing like:

If you go now to your browser, you will again see your app under your domain (in may case: https://testapp.xojodocs.com. Of course I will now delete my subdomain, but yours should be up and running.

The service is working as such that in case of any failure of the app (aka a reboot) it will again start automatically (after 3 seconds).

Welcome to Xojo Web 2 App Creator World and I hope you will enjoy this tutorial.

If you want to run multiple Xojo Web Apps on your server, I recommend to read the next tutorial:

How To Run Multiple Xojo Web Apps 2 on Your Server
In this article I described how to set up your own Linux server for deploying Xojo [https://xojo.com] Web 2 App. How To Build a Linux Server for Xojo Web 2With Xojo Web 2, it becomesrelativelyeasy to set up a Server and run yourfirst App. You would not even need an ownwebserver as a Xojo Web 2…

This article will show you how to automatically update your certificates:

Automatically Renewing Your Certificates
Now that you have built your secure Linux Server for Xojo Web 2, you might runinto issues around 90 days latest! How To Build a Linux Server for Xojo Web 2With Xojo Web 2, it becomesrelativelyeasy to set up a Server and run yourfirst App. You would not even need an ownwebserver as a Xojo Web 2 …

Please don't be shy to leave me a comment in case of any further questions.

Comments

Sign in or become a jeannot-muller.com member to join the conversation.
Just enter your email below to get a log in link.



You’ve successfully subscribed to jeannot-muller.com
Welcome back! You’ve successfully signed in.
Great! You’ve successfully signed up.
Your link has expired
Success! Check your email for magic link to sign-in.