Application Install Scripts

The install script should do everything and anything necessary to make an app work out of the box. Simple as that. :)

The install and uninstall scripts are executed in the webapp directory for the app. You should not code absolute paths in the (un)install scripts. You can use $PWD if you really have to. Apps may be install in different environments in the future, such as when two instance of an app are installed.

You should also not make assumptions about application names.

Say, for an application whose name has been assigned as

     foobar

The scripts are run in this directory

    /var/hda/web-apps/foobar

However, if the user already has an app called foobar, this new app being installed may be called foobar-2 or foobar-3 ... etc. In the future we may support the installation of multiple instances of a single webapp (e.g. multiple wikis in a school).

Useful Things

The install script can use some utility scripts (we expect to improve on these as time goes on, so please feel free to ask for things to be canned as scripts as you see the need!). See below for

Running Perl/Pyton/Ruby/Other scripts

By default, scripts are run in bash.

However, if you start your script by

  #!

Then they will be executed with whatever you provide there, e.g.:

  #!/usr/bin/perl
  #!/usr/bin/python
  #!/usr/bin/ruby

Running the scripts by hand

You can run the script by hand to test. This can simplify the debugging a lot.

mkdir -p /tmp/my-webapp-test
cd /tmp/my-webapp-test
wget http://url-for-muy-tar-ball-or-zip-file.tgz
untar/unzip mytarball
mv main-dir html
then run the script here ...

Use of inline files with EOF

You can typically create or patch files with inline text files:

    cat > foo.bar << EOF
    some
    $PWD
    here
    EOF

The above will create a file called foo.bar and have three lines. The second like will have a path. i.e. any $-variables will be substituted.

When the EOF is quoted with 'EOF' there will be no substitution:

    cat > foo.bar << 'EOF'
    some
    $PWD
    here
    EOF

The second line will have $PWD.

You can also feed inline files to patch (read man patch) with diffs that will then be used to patch files on the fly.

Here is a quick guide to make install scripts easier with Patch and diff

The hda-install-file utility script

This utility script will install files with some details of the local installation replaced, namely:

@HDA_NETWORK@  --> 192.168.1    (the network)
@HDA_SELF@     --> 10           (the ip address of the HDA)
@HDA_DOMAIN@   --> home.com     (the domain)
@HDA_NETMASK@  --> 255.255.255  (the netmask)
@HDA_NICKNAME@ --> <nick>       (the nickname of the dyndns - <nick>.yourhda.com)

please don't assume much and use as generally as possible, as these may support more general settings in the future (like a more general netmask, etc.)

The amahi-download utility script

This script is useful to more securely download files in install scripts. It's used with a URL and the sha1sum of the file it's meant to download:

amahi-download -h
Usage: /usr/bin/amahi-download [options] <filename|url> <sha1sum>
     -h, --help                       Show this help message.

This script will exit with a failure if the download fails or the checksum signature fails to check.

To change the contents of a file while installing an webapp

i.e. you would need this to edit configuration files for one-click installs in HDA.

for the examples i will use the (actually in development) configuration-file of the piwik-web-app.

example source (empty example-config-file delivered by piwik package): [file.orig]

<?php exit; ?> DO NOT REMOVE THIS LINE

this file is just here for documentation purpose

the config.ini.php is normally created during the installation process

when this file is absent it triggers the Installation process

the config.ini.php file contains information about the super user and the database access

[superuser] login = yourSuLogin password = yourSuPassword email = hello@piwik.org

[database] host = localhost username = databaseLogin password = datatabasePassword dbname = databaseName adapter = PDO_MYSQL ; PDO_MYSQL or MYSQLI tables_prefix = piwik_

example goal (in the config file after this process): [changed.orig]

<?php exit; ?> DO NOT REMOVE THIS LINE

file automatically generated during the piwik installation process (and updated later by some other plugins)

[superuser] login = admin password = 34131c9eef54abfe3aaed6fa275d01dd email = admin@hda.@HDA_DOMAIN@

[database] host = localhost username = root password = "hda" dbname = piwik adapter = PDO_MYSQL port = 3306

tables_prefix	= piwik_

What we have to do to achive this is to write a script. ;) We need to get the differences between the files. For this we will use diff-command. you got the files orig.file and changed.file. Now we need to diff them! use the shell for this and type (inside that folder) diff -U orig.file changed.file > my.diff

After you've done this, you got a file named my.diff. Inside it you got the code which you need to add inside your inside script. :)

hda-create-db-and-user utility script

Utility Script for creating a MySQL database and user for accessing the newly created database.

Usage: hda-create-db-and-user [options] dbname

   -u, --user=name                  Specifies the user name to use.
                                    Default: dbname@localhost
   -p,                              Specifies the password for the user
                                    Default: user name used above
   -d, --drop                       Drops the user and the DB.
                                    Default: dbname@localhost

   -h, --help                       Show this help message.

By default: the database, the user and the user's password are all the same. The user is always username@localhost.

Example: To create a database named foo hda-create-db-and-user foo

To drop the same database hda-create-db-and-user -d foo

Make an app start when the server (re)boots

The best way to have your app start when the computer boots/reboots is to add an entry to the crontab. Since the install scripts are run by the user 'apache', you can only add entries to apache's crontab. This means you cannot start any apps that require root privileges.

Here is an example:

First use the techniques from above to create the crontab entry that starts your app/daemon/server. the line starting with @reboot is the crontab entry. at the end of the crontab entry put a comment that is unique to your app. It will be used to remove the crontab item later during uninstall.

   cat > run_web-app.cron << EOF
   @reboot $PWD/html/web-app.py -d # web-app
   EOF

This made a file called web-app.cron in your apps folder. web-app.py is the program that will run as the system starts.

Next; the first line lists all the items in the current crontab, and copys it to a temp file. the second line add's our crontab enty to the bottom of the file. the third line loads the contents of the temp file back into the users crontab.

   crontab -l | grep -v "no crontab for" > /tmp/crontab.txt # copy the current crontab to a tempfile
   cat run_web-app.cron >> /tmp/crontab.txt #add our apps line to the tempfile
   crontab /tmp/crontab.txt #make the tempfile the crontab

NOTE The script's that manipulate the crontab needs to be carefully crafted. If not coded correctly, the users crontab will be overwritten!

Make sure that if you add an entry to the crontab that you have the uninstall script remove it. Here the first line list's all enties in the crontab and grep removes any line with the string "web-app" in it. this is why it is important to use a unique identifyer at the end of your crontab line. The remaining items from the crontab go into a tempfile then the contents of the tempfile are loaded into the users crontab again.

   crontab -l | grep -v web-app > /tmp/web-app-uninstall-crontab.txt
   crontab /tmp/web-app-uninstall-crontab.txt

Clean up

Have fun creating your apps. If you need something ask at IRC :)