app(1)
======

NAME
----
app - your favorite application manager

SYNOPSIS
--------
[verse]
'app' <options>

DOCUMENTATION
-------------

QUICK START
~~~~~~~~~~~

---------------------------------------------------------------------
$ app init -d my-app maven org.example:my-app:1.0-SNAPSHOT
$ cd my-app
$ app start
$ app conf set app.version 1.0
$ app upgrade
$ app restart
---------------------------------------------------------------------

INSTALLING AN APPLICATION
~~~~~~~~~~~~~~~~~~~~~~~~~

This resolved and downloads an appliaction from a Maven repository:

---------------------------------------------------------------------
$ app init -d my-app maven org.example:my-app:1.0-SNAPSHOT
---------------------------------------------------------------------

By default it will download from the central repository, but this is
not always what you want. To get it to use another repository give the
`-r` option:

---------------------------------------------------------------------
$ app init -d my-app maven -f http://repo.example.org/snapshots org.example:my-app:1.0-SNAPSHOT
---------------------------------------------------------------------

UPGRADING AN APPLICATION
~~~~~~~~~~~~~~~~~~~~~~~~

If your application is configured with the Maven resolver and the
version is a SNAPSHOT version, you can use this to upgrade your
application through a cron job:

---------------------------------------------------------------------
$ app upgrade
---------------------------------------------------------------------

With the resolver will try to resolve `app.version` to the latest
version. If it's change it will automatically download and install the
latest version.

CHANGING VERSION OF AN APPLICATION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

---------------------------------------------------------------------
$ app conf set app.version 1.0
$ app sync-version
---------------------------------------------------------------------

`app-sync-version` will first run the resolver to resolve the version
and if that has changed, it will download and install the new version.

CREATING APPS
-------------

An "app" is in itself nothing more than a zip archive with a particular
layout. In the root of the zip archive there must be a directory called
`root`. You can also place a file called `app.config` at the root. The
config file will be imported into the app's configuration. It is also
possible to run appliations before and after appliations are installed
through hooks. These are placed in a `hooks` directory, also at the
root of the archive.

To summarize, this is what an application zip archive looks like:

---------------------------------------------------------------------
/app.conf
/root
/root/bin
/root/bin/my-app
/root/repo/
/root/repo/io
/root/repo/io/trygvis/
/root/repo/io/trygvis/...
/hooks/
/hooks/post-install
---------------------------------------------------------------------

If this looks familiar to RPMs, Debs or Pkg files, you're right.

HOOKS
~~~~~

TODO

CREATING LAUNCHERS
~~~~~~~~~~~~~~~~~~

Trick when you don't know why your app won't start:

---------------------------------------------------------------------
exec 1>/tmp/myapp.out
exec 2>/tmp/myapp.err
---------------------------------------------------------------------

Make sure you _always_ use `exec` when spawning the actual app. This
makes sure that the pid operator records the correct PID. If you don't
do this the application will run, but will be reported as crashed when
you run 'app status'.

If you can't use `exec` or the application demands to deamonize itself
(like Apache Httpd), you have to set the configuration option
`app.pid_management=launcher`. Then the launcher is responsible for
creating the PID file under $APP_HOME/.app/pid. You can create a
symlink to the actual PID file if you can't customize where the app
places the file.

TODOs
-----

* Consider renaming "upgrade" to "refresh" or "sync". Upgrade is an
  overloaded word, in particular since it might mean to download a
  catalog of applications instead of actually upgrading it. I'm always
  confused if I should use "upgrade" or "update".

* Find a way to check if an application is running.

SEE ALSO
--------

linkman:app-cat-conf[1],
linkman:app-conf[1],
linkman:app-install-file[1],
linkman:app-operator-pid[1],
linkman:appinternals[1]

// vim: set ft=asciidoc: