Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
174 lines (132 sloc) 5.09 KB

app(1)

NAME

app - your favorite application manager

SYNOPSIS

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

appmgr is a pragmatic approach to managing a set of apps on a server. It is heavily inspired by Git’s approach in its command line interface and scriptability.

It handles installation aspects like downloading, unpacking and upgrading, as well as operational aspects like starting, stopping and basic configuration.

The package contains a set of tools that can be used directly on the command line, or through your own extensions.

Requirements

  • Linux. OS X and Cygwin are possible to support, but it’s not tested there yet. Solaris is also doable.

  • Bash 4 and "standard" GNU userland.

  • If using Maven: xmlstarlet

INSTALLING AN APPLICATION

This resolves and downloads an application 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 use another repository, add 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 upgrade your application through a cron job using a command like this:

$ app upgrade

The resolver will try to resolve app.version to the latest version. If it’s changed, 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 configuration file will be imported into the app’s configuration. It is also possible to run applications before and after applications 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.config
/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 you think 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/my-app.out
exec 2>/tmp/my-app.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 demonize 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 whether I should use "upgrade" or "update".

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

  • Make app.state a core feature. Possible values are enabled and disabled.

SEE ALSO

linkman:app-cat-conf[1], linkman:app-conf[1], linkman:app-disable[1], linkman:app-enable[1], linkman:app-init[1], linkman:app-install-file[1], linkman:app-operator-pid[1], linkman:app-start[1], linkman:app-stop[1], linkman:appinternals[7]