Build and run your first UBOS standalone App
/docs/development/tutorials-gears/first-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.
Note
If you are running this tutorial in a virtual machine, you must use a browser in the virtual machine to access this URL. Your host system does not know about the UBOS container inside your virtual machine and could not reach it anyway.
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.
-
Make your change, say, change one of the PHP files of the App.
-
Run the build again:
% makepkg -C -f
-
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.