Build and run your first UBOS standalone App

In this tutorial, you will be building, deploying and running a simple PHP web application as a standalone App on UBOS.

We will be using the “Glad-I-Was-Here” toy guestbook App, because it is very easy to understand.

This tutorial should take about 20-30 minutes.

Prerequisites

This tutorial assumes you have set up your development container setup as described in Developer setup.

Continue here once you have your development container running, and a non-root (ubosdev) shell open in the container.

Check out the source code for your project

In the ubosdev shell in the container, check out the code for your project, such as:

% mkdir ~/projects
% cd ~/projects
% git clone https://gitlab.com/ubos/ubos-toyapps.git

(You could actually do this on your Linux host, because the home directory is mapped 1-to-1 into the container. However, the build and test steps below need to be done in the container.)

Check that there is no App running in the container

On your Linux host, run a browser such as Firefox, and go to http://ubos-develop-yellow/. This will show a web page saying “No such site”.

Adjust the hostname if you named your UBOS container something else.

Build the App

In the container, go to the directory that contains the PKGBUILD for our example and build the package:

% cd ~/projects/ubos-toyapps/gladiwashere-php-mysql
% makepkg -C -f

This creates a package containing your App and associated metadata. We will install it in the next step.

Install the App

To install the package, in the container, run:

% sudo pacman -U gladiwashere-php-mysql-*.pkg*

(We use wildcards in these instructions, because the actual version number and extension may change over time. Of course you can use the actual filename.)

Now we have the code in the right places, but the web server and database are not configured yet to actually run the App. You can verify that there is still no App or Site by refreshing your web browser.

We will deploy the App in the next step.

Deploy the App

To create a website, deploy the App to the website, and do all necessary provisioning – like setting up a Mariadb database – we use the ubos-admin sub-command createsite. In the container, execute:

% sudo ubos-admin createsite

Enter * (the Wildcard hostname) as the hostname, and a reasonable user id, username, password and e-mail address (this toy app doesn’t actually use any of them, so the values don’t matter in this tutorial.)

When asked for the first App to run, enter gladiwashere-php-mysql and an empty string for the context path and the Accessories.

It will say “Deploying…” and then take a little while because various dependencies need to be downloaded and installed, such as Mariadb.

Try out your deployed App!

Now refresh your web browser. You will find your guestbook toyapp there. Feel free to enter some data.

Make a change to your deployed App

The update cycle is a bit faster than the initial setup.

1. Make your change, say, change one of the PHP files of the App.

2. Run the build again:

   % makepkg -C -f
   

3. Redeploy the already-deployed site with:

   % sudo ubos-admin update -v --pkg gladiwashere-php-mysql-*.pkg*
   

This last step will undeploy your previous Site configuration, install the new version of the code, redeploy the same Site configuration, and restore any data that you entered. It would even run database migrations if it needed to (but it doesn’t; this is a simple toy App).

Other ubos-admin operations

You can now try out other ubos-admin subcommands such as backup, restore, or undeploy. They are described in Command reference.

Undeploy your site

When you are done, undeploy the Site running the “Glad-I-Was-Here” App with:

% sudo ubos-admin undeploy --all

Refresh your web browser to verify it is gone.

Next steps

We recommend you work through How to package UBOS standalone Apps built with a variety of languages.