Documentation:

Hello World

Our version of Hello World is an extremely simple Web applications that that just displays “Hello World” in a user’s web browser. We use it to give you a taste for what is involved to package a real web application for UBOS. Here is a complete :-) screen shot:

../../_images/helloworld-screenshot.png

To obtain the source code:

> git clone https://github.com/uboslinux/ubos-toyapps

Go to subdirectory helloworld.

Package lifecycle and app deployment

The first thing to understand about how UBOS apps are packaged and deployed is the lifecycle of a package from the developer’s perspective, and then how a user deploys and undeploys the app contained in the package to their website:

  1. The developer creates the files for the package. If you have cloned the git repository above, you find the files for helloworld in directory helloworld; or you can browse them on github. They area:

    • index.php: minimalistic PHP file printing “Hello World”
    • htaccess: Apache configuration file that makes Apache default to index.php when the app is installed
    • PKGBUILD: script used to create the package (see below)
    • ubos-manifest.json: UBOS meta-data file (see below)
    • appicons: icon files (optional) that will be used for the icon the user can click on to visit the app
  2. The developer creates the package by executing, in its root directory:

    > makepkg -f
    

    This will create the package file named helloworld-*-any.pkg.tar.xz (where * is a particular version number defined in the PKGBUILD file). makepkg is the packaging command for pacman packages, the types of packages we use in UBOS. (You can read more about pacman on the Arch Linux Wiki.)

  3. Once the package has been created, the developer makes the package available to the user. In the general case, this involves uploading the package to the UBOS depot, UBOS quality assurance etc etc, but for our purposes here, ignore all that and simply assume that the package file created by the developer has somehow arrived on the user’s UBOS device, such as by file transfer.

  4. The user installs the package on the target device:

    > sudo pacman -U helloworld-*-any.pkg.tar.xz
    

    This command will install a locally built package locally, but it is equivalent to what happens when a user obtains the same app via the UBOS Depot.

    Note that this unpacks the package on the hard drive and runs whatever installation scripts that the package specifies (the latter is rare, e.g. Hello World does not have such scripts). However, installing the package does not deploy the app at any site or virtual host. To do that, see the next step:

  5. The user installs this web app at a particular virtual host:

    > sudo ubos-admin createsite
    

    Answer the questions it asks, and use the app name helloworld (see also Setting up your first web app)

    This will put all the right files in the right web server directories, activate needed Apache modules, restart servers, and the like. When this command completes, the app is ready for use.

  6. The user can now visit the fully deployed app at the respective URL at which it was installed.

  7. Now assume that a new version of the package is available. If the new package is available locally, the user can perform a software upgrade of the helloworld package (only):

    > sudo ubos-admin update --pkgfile <pkgfile>
    

    where <pkgfile> is a new version of the package file created as shown above. If distributed through the UBOS Depot, the argument --pkgfile will be omitted, and UBOS will upgrade all software on the host to the most recent version.

  8. Undeploy the app by undeploying the entire virtual host. This will keeps the package installed:

    > sudo ubos-admin undeploy --siteid <siteid>
    

    where <siteid> is the identifier of the installed site.

  9. If the user wishes to remove the package entirely:

    > sudo pacman -R helloworld
    

Anatomy of the package

The PKGBUILD script’s package method puts the package together:

package() {
# Manifest
    mkdir -p ${pkgdir}/var/lib/ubos/manifests
    install -m0644 ${startdir}/ubos-manifest.json ${pkgdir}/var/lib/ubos/manifests/${pkgname}.json
# Icons
    mkdir -p ${pkgdir}/srv/http/_appicons/$pkgname
    install -m644 ${startdir}/appicons/{72x72,144x144}.png ${pkgdir}/srv/http/_appicons/$pkgname/
    install -m644 ${startdir}/appicons/license.txt ${pkgdir}/srv/http/_appicons/$pkgname/
# Code
    mkdir -p ${pkgdir}/usr/share/${pkgname}
    install -m755 ${startdir}/index.php ${pkgdir}/usr/share/${pkgname}/
    install -m644 ${startdir}/htaccess ${pkgdir}/usr/share/${pkgname}/
}

You can see that this script creates three directories, and installs a few files in them. The Arch Linux wiki describes PKGBUILD; there is nothing UBOS-specific about this.

This corresponds to what the package file contains after makepkg has completed:

> tar tfJ helloworld-*-any.pkg.tar.xz
.PKGINFO
.MTREE
srv/
srv/http/
srv/http/_appicons/
srv/http/_appicons/helloworld/
srv/http/_appicons/helloworld/72x72.png
srv/http/_appicons/helloworld/144x144.png
srv/http/_appicons/helloworld/license.txt
usr/
usr/share/
usr/share/helloworld/
usr/share/helloworld/index.php
usr/share/helloworld/htaccess
var/
var/lib/
var/lib/ubos/
var/lib/ubos/manifests/
var/lib/ubos/manifests/helloworld.json
../../_images/helloworld-icon.png

The first two files, .PKGINFO and .MTREE are metadata that is automatically generated by makepkg.

Then, the files below srv/http/_appicons/ are simply graphics files that can be used by UBOS to show to the user a logo for the application. This image is shown to the right. They are optional and are added in the package() section of PGKBUILD.

usr/share/helloworld contains the files that constitute the application. For this extremely simple app, there are only two: the PHP code that emits the “Hello World” HTML, and an Apache htaccess file so this HTML is emitted even if the path ends with a slash instead of index.php. More complex web apps would put the bulk of their code and auxiliary files there.

Finally, var/lib/ubos/manifests/ contains the UBOS Manifest JSON file for this application, which describes what needs to happen upon ubos-admin deploy and when other ubos-admin commands are executed.

App manifest

For this app, the manifest file looks as follows:

{
  "type" : "app",

  "roles" : {
    "apache2" : {
      "defaultcontext" : "/hello",
      "depends" : [
        "php",
        "php-apache"
      ],
      "apache2modules" : [
        "php7"
      ],
      "appconfigitems" : [
        {
          "type"         : "file",
          "name"         : "index.php",
          "source"       : "index.php",
        },
        {
          "type"         : "file",
          "name"         : ".htaccess",
          "source"       : "htaccess",
        }
      ]
    }
  }
}

Let’s discuss these items in sequence:

  • "type" : "app" declares this to be an app, not an accessory.
  • This app only uses a single role: apache2. Apps could also specify other roles, such as mysql if they make use of MySQL in addition to Apache.
  • By default, this app wants to be deployed at the relative path /hello of a virtual host. This can be overridden by the user in the Site JSON file or when entering a different path during execution of ubos-admin createsite.
  • For the apache2 role, this app requires packages php and php-apache, as it is a PHP app. It requires that the Apache module php7 has been enabled before it can be run.
  • Finally, each installation of this app requires two files to be installed in the web server’s document directory tree: a file called index.php, which is simply copied, and a file called .htaccess which is copied from a slightly different name. By convention, the “source” path is relative to the package installation directory /usr/share/helloworld; and the destination path is relative to the correct directory from which Apache serves files, given the virtual host and context at which the app runs. Here, this may be /srv/http/sites/sa6e789f5d919c464d2422f6620eaf9cba789c4a5/hello/ (auto-provisioned by UBOS).

When the user invokes ubos-admin deploy, UBOS processes the manifest and “makes it so”. We recommend you package and then helloworld with the example commands above, and then examine how UBOS made the app appear.

When the user invokes ubos-admin undeploy, UBOS processes the manifest in reverse sequence, and restores the system to its previous state.