[Webapps-common-discuss] [commit] r83 - in trunk: debian debian/po
doc dpkg examples/webapp-apache-dbapp-example/debian
Sean Finney
seanius at costa.debian.org
Tue May 16 16:51:40 UTC 2006
Author: seanius
Date: 2006-05-16 16:51:39 +0000 (Tue, 16 May 2006)
New Revision: 83
Modified:
trunk/debian/changelog
trunk/debian/po/templates.pot
trunk/debian/rules
trunk/debian/webapps-common.templates
trunk/doc/webapps-common.sgml
trunk/dpkg/postinst
trunk/dpkg/postrm
trunk/dpkg/prerm
trunk/examples/webapp-apache-dbapp-example/debian/config
trunk/examples/webapp-apache-dbapp-example/debian/postinst
trunk/examples/webapp-apache-dbapp-example/debian/postrm
trunk/examples/webapp-apache-dbapp-example/debian/prerm
Log:
new and better examples, bug fixes, documentation updates.
Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/debian/changelog 2006-05-16 16:51:39 UTC (rev 83)
@@ -10,8 +10,10 @@
* make sure cut expressions inlcude -s where appropriate
* initial support for integration with dbconfig-common(!). currently,
this only works for single-instance installs.
+ * update to the debconf template descriptions.
+ * update to the webapps-common.sgml documentation.
- -- sean finney <seanius at debian.org> Tue, 09 May 2006 23:47:15 +0200
+ -- sean finney <seanius at debian.org> Tue, 16 May 2006 11:35:25 -0500
webapps-common (0.6) UNRELEASED; urgency=low
Modified: trunk/debian/po/templates.pot
===================================================================
--- trunk/debian/po/templates.pot 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/debian/po/templates.pot 2006-05-16 16:51:39 UTC (rev 83)
@@ -8,7 +8,7 @@
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: seanius at debian.org\n"
-"POT-Creation-Date: 2006-05-15 14:24-0500\n"
+"POT-Creation-Date: 2006-05-16 11:35-0500\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL at ADDRESS>\n"
"Language-Team: LANGUAGE <LL at li.org>\n"
@@ -170,44 +170,75 @@
msgstr ""
#. Type: select
+#. Choices
+#: ../webapps-common.templates:83
+msgid "=global=, new vhost, ${virtualhosts}"
+msgstr ""
+
+#. Type: select
#. Description
-#: ../webapps-common.templates:83
+#: ../webapps-common.templates:84
msgid "Please select a virtualhost with which to configure ${pkg}"
msgstr ""
#. Type: select
-#. Choices
+#. Description
#: ../webapps-common.templates:84
-msgid "=global=, new vhost, ${virtualhosts}"
+msgid ""
+"If you want to configure this application for the default site available "
+"from your webserver, you should select \"=global=\". If you wish to "
+"configure the application to run on a virtualhost that does not appear in "
+"the list of choices, you can select \"new vhost\"."
msgstr ""
#. Type: multiselect
#. Description
-#: ../webapps-common.templates:88
+#: ../webapps-common.templates:93
msgid "Please select the instances to configure for ${pkg}"
msgstr ""
#. Type: multiselect
+#. Description
+#: ../webapps-common.templates:93
+msgid ""
+"This application supports multiple simultaneous installations. You may "
+"configure any number of site/directory combinations by continuing to select "
+"\"configure new instance\". You can also de-configure an instance at any "
+"time by unselecting the given instance."
+msgstr ""
+
+#. Type: multiselect
#. Choices
-#: ../webapps-common.templates:93
+#: ../webapps-common.templates:101
msgid "configure new instance, ${instances}"
msgstr ""
#. Type: string
#. Description
-#: ../webapps-common.templates:97
+#: ../webapps-common.templates:105
msgid "Please provide the subdirectory for ${pkg} on ${vhost}"
msgstr ""
+#. Type: string
+#. Description
+#: ../webapps-common.templates:105
+msgid ""
+"The subdirectory that you provide will be the directory from which the "
+"application is externally accessed. You may provide a nested subdirectory "
+"name, or provide no directory name at all, in which case the application "
+"will serve as the \"DocumentRoot\" of the particular virtualhost/site for "
+"which you configure the application."
+msgstr ""
+
#. Type: multiselect
#. Description
-#: ../webapps-common.templates:102
+#: ../webapps-common.templates:115
msgid "Select the web servers to reload."
msgstr ""
#. Type: multiselect
#. Description
-#: ../webapps-common.templates:102
+#: ../webapps-common.templates:115
msgid ""
"Due to configuration changes, some of your webservers may need to be "
"reloaded. You may de-select servers from the given list if you do not wish "
Modified: trunk/debian/rules
===================================================================
--- trunk/debian/rules 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/debian/rules 2006-05-16 16:51:39 UTC (rev 83)
@@ -26,7 +26,7 @@
build-stamp: configure-stamp
dh_testdir
touch build-stamp
-ifeq ($(builddocs),yes)
+ifneq ($(builddocs),no)
make -C doc
endif
@@ -49,9 +49,6 @@
cp -Pr internal debian/webapps-common/usr/share/webapps-common/
cp -Pr dpkg debian/webapps-common/usr/share/webapps-common/
cp -Pr templates debian/webapps-common/usr/share/webapps-common/
- rm -rf debian/webapps-common/usr/share/webapps-common/internal/CVS
- rm -rf debian/webapps-common/usr/share/webapps-common/dpkg/CVS
- rm -rf debian/webapps-common/usr/share/webapps-common/templates/CVS
# Build architecture-independent files here.
binary-indep: build install
Modified: trunk/debian/webapps-common.templates
===================================================================
--- trunk/debian/webapps-common.templates 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/debian/webapps-common.templates 2006-05-16 16:51:39 UTC (rev 83)
@@ -80,13 +80,21 @@
Template: webapps-common/httpd/virtualhost
Type: select
+_Choices: =global=, new vhost, ${virtualhosts}
_Description: Please select a virtualhost with which to configure ${pkg}
-_Choices: =global=, new vhost, ${virtualhosts}
+ If you want to configure this application for the default site available
+ from your webserver, you should select "=global=". If you wish to
+ configure the application to run on a virtualhost that does not appear
+ in the list of choices, you can select "new vhost".
Template: webapps-common/httpd/instances
Type: multiselect
+_Choices: configure new instance, ${instances}
_Description: Please select the instances to configure for ${pkg}
-_Choices: configure new instance, ${instances}
+ This application supports multiple simultaneous installations. You
+ may configure any number of site/directory combinations by continuing
+ to select "configure new instance". You can also de-configure an instance
+ at any time by unselecting the given instance.
Template: webapps-common/httpd/instances_previous
Type: multiselect
@@ -95,6 +103,11 @@
Template: webapps-common/httpd/website_subdirectory
Type: string
_Description: Please provide the subdirectory for ${pkg} on ${vhost}
+ The subdirectory that you provide will be the directory from which the
+ application is externally accessed. You may provide a nested subdirectory
+ name, or provide no directory name at all, in which case the application
+ will serve as the "DocumentRoot" of the particular virtualhost/site for
+ which you configure the application.
Template: webapps-common/httpd/reload
Type: multiselect
Modified: trunk/doc/webapps-common.sgml
===================================================================
--- trunk/doc/webapps-common.sgml 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/doc/webapps-common.sgml 2006-05-16 16:51:39 UTC (rev 83)
@@ -36,8 +36,9 @@
configurations files
<item>alternatively generate web server configuration by using
variable substitution into maintainer-supplied templates
- <item>NOTYET: integrated support for database applications
- via dbconfig-common (dbc needs manydb support)
+ <item>integrated support for database applications
+ via dbconfig-common (XXX: for "single instance" installs only,
+ currently)
<item>prompt users with a set of normalized, pre-translated questions
<item>NOTYET: handle failures gracefully, with an option to retry.
<item>work for package maintainers with little effort on their part
@@ -55,147 +56,122 @@
<strong>BIG DISCLAIMER</strong>: this is a work in progress.
standard it-breaks-you-keep-the-pieces disclaimer here. I'm not
even promising i won't even change the API at this point.
- <p>
- Okay, so this all sounds great... but how do I use it in my
- package, you ask? This may depend on your particular needs,
- but chances are you can do so by simply putting some simple
- commands and variables in your maintainer scripts, and
- of course updating your dependencies.
- <sect id="installtype">Choose your method of configuration
+ <sect id="quickndirty">Quick and dirty: what to do
<p>
- The first step depends largely on the application
- you are packaging, and how complicated the webserver
- configuration file needs to be. Because of this, there
- are currently three different methods you can use for
- installing via webapps-common:
- <taglist>
- <tag>simple
- <item>the easiest method to use, but also the least
- flexible. it works by automatically generating web
- server configuration files based on the input from
- the admin during installation. if your application
- requires additional specific directives (setting
- php flags, for example) this method will not work
- for you.
- <tag>inline
- <item>works by injecting the contents of a file you
- provide into the "middle" of the generated
- configuration files. If your package only needs
- a few extra configuration options set, this may
- be the option for you.
- <tag>template
- <item>works by copying a file you provide, and performing
- some simple variable-substitution before putting
- the file in place. This is probably the most
- powerful of the three options, but also the most
- complex, as then the burden is put on you to
- make sure the file in question will support the
- various combinations of ways in which someone would
- install your package (subdir, vhost, etc). TODO:
- more documentation on this.
- </taglist>
- <sect id="simple">The simplest example - "simple"
+ Okay, so this all sounds great... but how do I use it in my
+ package, you ask? For the simplest of installations, you
+ basically need to do three things:
+ <list>
+ <item>Provide a template web-server configuration file
+ <item>Place the required webapps-common hooks in your maintainer scripts
+ <item>update your package to depend on webapps-common
+ </list>
+ <sect1 id="template">Providing template web-server configuration
+ <p>
+ during configuration, webapps-common will look
+ for a template webserver file in the location
+ <file>/usr/share/webapps-common/install/PACKAGE/httpd/apache_template</file>.
+ <p>
+ <strong>TODO</strong>: the location is ugly, and the documentation
+ is apache-specific.
+
+ <p>
+ The configuration file should contain everything needed for
+ the application to properly function. Additionally, it should
+ contain macros to be expanded by webapps-common that will
+ make it customizable based on how the local admin has
+ chosen to install the application. here is an example
+ of such configuration:
+ <example>
+ # this is a sample template-based configuration file for apache.
+ # this file will be included as-is, with the exception that
+ # certain substitutions will occur with the result
+
+ _WC_DOCROOT_DIRECTIVE_ /usr/share/foo/www
+ <Directory /usr/share/foo/www>
+ # other settings here that relate to your application
+ # for example, if your app ships with its own php libraries:
+ php_value include_path ".:/usr/share/foo/lib"
+ </Directory>
+ </example>
+ <p>
+ In the above example, the most important part
+ is the _WC_DOCROOT_DIRECTIVE_, which will
+ conditionally expand to either an Alias or
+ DocumentRoot directive depending on how the
+ application is configured.
+ <p>
+ For a full list of substitution variables, see <ref id="substvars">.
+
+ <sect1 id="hooks">Putting in maintainer script hooks
+ <p>
+ Next, you will need to insert the webapps-common maintainer script
+ hooks into your package's maintainer scripts, which consists of
+ sourcing a particular shell script library, possibly setting
+ a few variables to influence the behaviour of
+ webapps-common (see <ref id="hookvars"> for a full list),
+ and then calling the <var>wc_go</var> function with the package
+ name followed by the arguments passed to the maintainer script.
+ The following example illustrates how this would be done in
+ the config maintainance script.
+ <example>
+ . /usr/share/debconf/confmodule
+ . /usr/share/webapps-common/dpkg/config
+ wc_go PACKAGE $@
+ </example>
+ <p>
+ you must place these hooks into your
+ <var>config</var>, <var>postinst</var>,
+ <var>prerm</var>, and <var>postrm</var> scripts
+ (or in otherwords in every maintainer script
+ except the <var>preinst</var>).
+ <sect id="examples">Working Examples
<p>
- In the simplest case, you can activate webapps-common by
- adding two lines in your config, prerm, postinst, and
- postrm maintainer scripts that source the appropriate
- webapps-common shell script library, and call the
- <var>wc_go</var> function. For example, the config
- script should contain:
- <example>
- . /usr/share/debconf/confmodule
- . /usr/share/webapps-common/dpkg/config
- wc_go PACKAGE $@
- </example>
- <sect id="inline">Using "inline" configuration
- <p>
- If the application your packaging requires some
- custom configuration, but not much, you might be
- interested in trying the "inline" method. Using
- this method is not much more complicated than the
- "simple" case. The only difference is that you need
- to specifically tell webapps-common to use this method,
- and provide the file with the configuration directives.
- <p>
- The maintainer scripts should then look something like:
- <example>
- . /usr/share/debconf/confmodule
- . /usr/share/webapps-common/dpkg/config
- wc_apache_conf_style="inline"
- wc_go PACKAGE $@
- </example>
- <p>
- Additionally, you will need to provide the actual content
- to be inlined. Let's imagine that you needed to have
- the following configuration for your application:
- <example>
- #
- # this is an example of an inline-included apache configuration.
- # the following configuration will be included in a "Directory"
- # block specific to this web application.
- php_value include_path .
- </example>
- <p>
- Then you would need to install a copy of this file as
- <file>/usr/share/webapps-common/install/PACKAGE/httpd/apache_inline</file>,
- which will automatically be detected and used by
- webapps-common.
- <sect id="template">Using "template" configuration
- <p>
- Perhaps your application requires a great deal of
- configuration, or has some other strange requirements
- such that the previous two methods will not work well
- for you. In that case, using the "template" method may
- be the best option. In this method, you supply a sample
- file with the requisite server configuration options,
- and then during the package configuration process certain
- variable substitutions occur in the final output.
- <p>
- The maintainer script code looks about the same:
- <example>
- . /usr/share/debconf/confmodule
- . /usr/share/webapps-common/dpkg/config
- wc_apache_conf_style="template"
- wc_go PACKAGE $@
- </example>
- <p>
- And then you will need to provide the template configuration
- file, which might look something like:
- <example>
- # this is a sample template-based configuration file for apache.
- # this file will be included as-is, with the exception that
- # certain substitutions will occur with the result
- Alias _WC_WEBSITE_SUBDIRECTORY_ /usr/share/PACKAGE/www
- </example>
- <p>
- <strong>TODO</strong>: this is actually a pretty crappy
- example, because it could be done with the "simple"
- method. Let's think of a better one.
- <p>
- This file would then be installed as part of your package in
- <file>/usr/share/webapps-common/install/PACKAGE/httpd/apache_template</file>.
- In this example, _WC_WEBSITE_SUBDIRECTORY_ would be
- substituted with the value of the subdirectory from which
- the application would be accessible on the webserver.
- <p>
- <strong>TODO</strong>: Generate a list of substitution
- variables and talk about how this works with virtualhost
- configs
- <sect id="examples">Working Examples
- <p>
If you would like to see working examples of packages
currently using webapps-common, grab the latest
webapps-common source from alioth, and look in the
examples subdirectory. This directory contains debian
source packages that generates packages implementing
- each of the above installation methods. just run
+ each of the above installation methods. Simply run
the included buildpackages.sh script to generate them.
<chapt id="advanced">Advanced Techniques and Concepts
<p> TODO
<chapt id="appendix">Appendix - Variables and Options
- <p> TODO
+ <sect id="hookvars">Maintainer script hook variables
+ <p>
+ The following list documents variables that you can set in your
+ maintainer scripts to influence the behaviour of webapps-common.
+ <taglist>
+ <tag>wc_multiple_instances (used in: <var>config</var>)
+ <item>set to any non-empty string to specify that this application
+ supports running on multiple instances. note that this is
+ still kind of experimental.
+ <tag>wc_dbapp (used in: <var>config</var>, <var>postinst</var>, <var>prerm</var>, <var>postrm</var>, <strong>but note this may change</strong>).
+ <item>set to any non-empty string to specify that this application
+ requires an underlying database. <strong>NOTE</strong> this
+ option currently conflicts with <var>wc_multiple_instances</var>.
+ <tag>wc_dbtype (used in: <var>config</var>, <var>postinst</var>, <var>prerm</var>, <var>postrm</var>, <strong>but note this may change</strong>).
+ <item>if your application requires a database, the database type.
+ </taglist>
+ <sect id="substvars">Configuration template substitution variables.
+ <p>
+ The following list documents the substituion variables which will
+ be expanded by webapps-common when generating web-server
+ configuration files.
+ <taglist>
+ <tag>_WC_DOCROOT_DIRECTIVE_
+ <item>expands to either Alias or DocumentRoot, depending on how
+ the package is being configured.
+ <tag>_WC_WEBSITE_SUBDIRECTORY_
+ <item>expands to the subdirectory from which the application is
+ configured to be externally accessed.
+ <tag>_WC_WEBSITE_HOSTNAME_
+ <item>expands to the name of the host on which the application
+ is configured. <strong>TODO</strong>: what happens for
+ default/global installs?
+ </taglist>
<chapt id="related"> Related Documents
<p>
Modified: trunk/dpkg/postinst
===================================================================
--- trunk/dpkg/postinst 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/dpkg/postinst 2006-05-16 16:51:39 UTC (rev 83)
@@ -57,7 +57,11 @@
wc_postinst_dbapp_support(){
if [ "$wc_dbapp" ]; then
- . /usr/share/dbconfig-common/dpkg/postinst
+ if [ "$wc_dbtype" ]; then
+ . /usr/share/dbconfig-common/dpkg/postinst.$wc_dbtype
+ else
+ . /usr/share/dbconfig-common/dpkg/postinst
+ fi
dbc_go $@
fi
}
Modified: trunk/dpkg/postrm
===================================================================
--- trunk/dpkg/postrm 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/dpkg/postrm 2006-05-16 16:51:39 UTC (rev 83)
@@ -18,10 +18,13 @@
wc_postrm_purge_app
fi
- # no, now let's do the dbconfig-support
if [ ! "$wc_multiple_instances" ]; then
if [ "$wc_dbapp" ]; then
- . /usr/share/dbconfig-common/dpkg/postrm
+ if [ "$wc_dbtype" ]; then
+ . /usr/share/dbconfig-common/dpkg/postrm.$wc_dbtype
+ else
+ . /usr/share/dbconfig-common/dpkg/postrm
+ fi
dbc_go $@
fi
fi
Modified: trunk/dpkg/prerm
===================================================================
--- trunk/dpkg/prerm 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/dpkg/prerm 2006-05-16 16:51:39 UTC (rev 83)
@@ -5,11 +5,14 @@
_wc_debug "(prerm) wc_go() $@"
# wc_config $@
- # no, now let's do the dbconfig-support
- if [ ! "$wc_multiple_instances" ]; then
- if [ "$wc_dbapp" ]; then
- . /usr/share/dbconfig-common/dpkg/prerm
- dbc_go $@
- fi
- fi
+ if [ ! "$wc_multiple_instances" ]; then
+ if [ "$wc_dbapp" ]; then
+ if [ "$wc_dbtype" ]; then
+ . /usr/share/dbconfig-common/dpkg/prerm.$wc_dbtype
+ else
+ . /usr/share/dbconfig-common/dpkg/prerm
+ fi
+ dbc_go $@
+ fi
+ fi
}
Modified: trunk/examples/webapp-apache-dbapp-example/debian/config
===================================================================
--- trunk/examples/webapp-apache-dbapp-example/debian/config 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/examples/webapp-apache-dbapp-example/debian/config 2006-05-16 16:51:39 UTC (rev 83)
@@ -5,5 +5,5 @@
. /usr/share/debconf/confmodule
. /usr/share/webapps-common/dpkg/config
wc_dbapp="yes"
-dbc_dbtype="mysql"
+wc_dbtype="mysql"
wc_go webapp-apache-dbapp-example $@
Modified: trunk/examples/webapp-apache-dbapp-example/debian/postinst
===================================================================
--- trunk/examples/webapp-apache-dbapp-example/debian/postinst 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/examples/webapp-apache-dbapp-example/debian/postinst 2006-05-16 16:51:39 UTC (rev 83)
@@ -5,7 +5,7 @@
. /usr/share/debconf/confmodule
. /usr/share/webapps-common/dpkg/postinst
wc_dbapp="yes"
-dbc_dbtype="mysql"
+wc_dbtype="mysql"
dbc_generate_include="php:/etc/webapp-apache-dbapp-example/settings.php"
dbc_generate_include_args="-O root:www-data -m 640"
wc_go webapp-apache-dbapp-example $@
Modified: trunk/examples/webapp-apache-dbapp-example/debian/postrm
===================================================================
--- trunk/examples/webapp-apache-dbapp-example/debian/postrm 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/examples/webapp-apache-dbapp-example/debian/postrm 2006-05-16 16:51:39 UTC (rev 83)
@@ -5,7 +5,12 @@
. /usr/share/debconf/confmodule
. /usr/share/webapps-common/dpkg/postrm
wc_dbapp="yes"
-dbc_dbtype="mysql"
+wc_dbtype="mysql"
wc_go webapp-apache-dbapp-example $@
+if [ "$1" = "purge" ]; then
+ rm -f /etc/webapp-apache-dbapp-example/settings.php
+ ucf --purge /etc/webapp-apache-dbapp-example/settings.php
+fi
+
#DEBHELPER#
Modified: trunk/examples/webapp-apache-dbapp-example/debian/prerm
===================================================================
--- trunk/examples/webapp-apache-dbapp-example/debian/prerm 2006-05-15 23:12:50 UTC (rev 82)
+++ trunk/examples/webapp-apache-dbapp-example/debian/prerm 2006-05-16 16:51:39 UTC (rev 83)
@@ -5,7 +5,7 @@
. /usr/share/debconf/confmodule
. /usr/share/webapps-common/dpkg/prerm
wc_dbapp="yes"
-dbc_dbtype="mysql"
+wc_dbtype="mysql"
wc_go webapp-apache-dbapp-example $@
#DEBHELPER#
More information about the Webapps-common-discuss
mailing list