From 1480338c5a3da5b6494565ab955ab67a15f19dd3 Mon Sep 17 00:00:00 2001 From: Trygve Laugstøl Date: Thu, 31 Oct 2013 21:52:24 +0100 Subject: app-init: Adding '-s' option to set a configuration option before the resolver is executed and app is installed. The configuration will be available when the app's hooks are executed. o Running the documentation though aspell. --- docs/Makefile | 7 +++++- docs/app-cat-conf.txt | 19 ++++++++-------- docs/app-init.txt | 58 +++++++++++++++++++++++++++++++++++++++++++++++ docs/app-install-file.txt | 2 +- docs/app.txt | 35 ++++++++++++++-------------- docs/appsh.dict | 1 + 6 files changed, 94 insertions(+), 28 deletions(-) create mode 100644 docs/app-init.txt create mode 100644 docs/appsh.dict (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index 355f0bc..9ad7712 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,12 +2,12 @@ TXT=$(wildcard *.txt) # Expand target section from heading of each page MAN=$(shell ls *.txt|xargs -n 1 head -n 1|sed "s,\(.*\)(\([0-9]\)),\1.\2,") HTML=$(patsubst %.txt,%.html,$(TXT)) +ASPELL=aspell all: html man html: $(HTML) man: $(MAN) - .PHONY: html man %.html: %.txt @@ -25,5 +25,10 @@ define man @a2x --format manpage $(1) endef +spell: $(patsubst %,spell-%,$(TXT)) +.PHONY: spell +spell-%: + $(ASPELL) check -p appsh.dict -l en --encoding utf-8 $(patsubst spell-%,%,$@) + clean: rm -rf $(wildcard *.html) $(wildcard *.1) $(wildcard *.7) diff --git a/docs/app-cat-conf.txt b/docs/app-cat-conf.txt index 57fe693..3b5501c 100644 --- a/docs/app-cat-conf.txt +++ b/docs/app-cat-conf.txt @@ -3,7 +3,7 @@ app-cat-conf(1) NAME ---- -app-cat-conf - outputs a combined configuration file in a parseable +app-cat-conf - outputs a combined configuration file in a parsable format SYNOPSIS @@ -19,14 +19,14 @@ output a key once, the last value for each key seen will win. A configuration file is a collection of grouped keys and values, similar to Git. -The keys consits of two parts: a _group_ and a _name_. Both have to +The keys consist of two parts: a _group_ and a _name_. Both have to match the regex `[a-zA-Z0-9]` and are combined with a dot. OPTIONS ------- -f:: - The config file to use. If the value is '-', stdin will be used as - input. The option can be given multiple times. + The configuration file to use. If the value is '-', stdin will be + used as input. The option can be given multiple times. -D:: Disables the inclusion of the default files. -k:: @@ -37,9 +37,10 @@ OPTIONS LOCATIONS AND DEFAULT FILES --------------------------- -'app-cat-conf' will by default look for configuration files in three places: +'app-cat-conf' will by default look for configuration files in three +places: -* '$APPSH_HOME/lib/default-config' +* '$APPSH_HOME/lib/default-configuration' * '$HOME/.appconfig' @@ -60,13 +61,13 @@ Support _default values_: when a key is missing, return the default value instead. Suggested option: '-d'. + Support _$APP_HOME_: If '$APP_HOME' is set, use that when reading the -app's config values. Makes it easier to script as the user may move -around directories, but still read values from the right place. +app's configuration values. Makes it easier to script as the user may +move around directories, but still read values from the right place. SEE ALSO -------- -git-config(1) +git-configuration(1) APP.SH ------ diff --git a/docs/app-init.txt b/docs/app-init.txt new file mode 100644 index 0000000..58b7a7c --- /dev/null +++ b/docs/app-init.txt @@ -0,0 +1,58 @@ +app-init(1) +=========== + +NAME +---- +app-init - Installs an application + +SYNOPSIS +-------- +[verse] +'app-init' [-s group.name=key ...] -d + +DESCRIPTION +----------- + +Similar to 'git clone', 'app-init' is the first command you use when +you want to deploy an application. It performs the following tasks: + +1. Create the '.app' directory and the config file. +2. Initialize the resolver +3. Run 'app upgrade' to install the initial version. 'app upgrade' + will also run any hooks defined in the application. + +OPTIONS +------- + +-d:: + The directory to create the application in. If the initialization + fails, the directory will be removed. +-s group.name=key:: + Add a configuration parameter before the resolver and any hooks are + fired. ++ +This option can be given multiple times. +:: + The name of the resolver to use. 'app-init' will search the path for + an executable called 'app-resolver-'. +:: + A list of arguments passed on directly to the resolver. See the + documentation of the resolver you're using for more details. + +BUILT-IN RESOLVERS +------------------ + +Appsh comes with two built-it resolvers: + +maven:: + See linkman:app-resolver-maven[1]. +file:: + See linkman:app-resolver-file[1]. + +APP.SH +------ + +Part of the linkman:app[1] suite. + +// vim: set ft=asciidoc: + diff --git a/docs/app-install-file.txt b/docs/app-install-file.txt index bb7cc48..e7525d1 100644 --- a/docs/app-install-file.txt +++ b/docs/app-install-file.txt @@ -8,7 +8,7 @@ app-install-file - Low-level installation of an app SYNOPSIS -------- [verse] -'app-operator-pid' ... +'app-install-file' ... TODOs ----- diff --git a/docs/app.txt b/docs/app.txt index 9e9afc0..38cf169 100644 --- a/docs/app.txt +++ b/docs/app.txt @@ -26,7 +26,7 @@ $ app restart --------------------------------------------------------------------- appsh 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 +It is heavily inspired by Git's approach in its command line interface and scriptability. It handles installation aspects: downloading, unpacking and upgrading, @@ -38,7 +38,7 @@ command line, or through your own extensions. Requirements ^^^^^^^^^^^^ -* Linux. OSX and Cygwin are possible to support, but it's not tested +* 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 @@ -46,7 +46,7 @@ Requirements INSTALLING AN APPLICATION ~~~~~~~~~~~~~~~~~~~~~~~~~ -This resolved and downloads an appliaction from a Maven repository: +This resolved and downloads an application from a Maven repository: --------------------------------------------------------------------- $ app init -d my-app maven org.example:my-app:1.0-SNAPSHOT @@ -89,13 +89,13 @@ 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. +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: @@ -125,18 +125,18 @@ CREATING LAUNCHERS Trick when you don't know why your app won't start: --------------------------------------------------------------------- -exec 1>/tmp/myapp.out -exec 2>/tmp/myapp.err +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 +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 +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 +`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. @@ -160,7 +160,8 @@ SEE ALSO linkman:app-cat-conf[1], linkman:app-conf[1], linkman:app-install-file[1], -linkman:app-operator-pid[1], -linkman:appinternals[1] +linkman:app-init[1], +linkman:app-operator-PID[1], +linkman:appinternals[7] // vim: set ft=asciidoc: diff --git a/docs/appsh.dict b/docs/appsh.dict new file mode 100644 index 0000000..aef5c87 --- /dev/null +++ b/docs/appsh.dict @@ -0,0 +1 @@ +personal_repl-1.1 en 0 -- cgit v1.2.3