Koha-community/Koha
13
7
Fork 0
Code Issues Releases Wiki Activity
Koha/debian/docs/koha-create.xml
Tomas Cohen Arazi c6f091cc23 Bug 10733: Memcached on package installs 
This patch makes the koha-create script adjust the koha-conf.xml file
with the proper string substitutions to enable the use of memcached
for the created Koha instance.

It adds three option switches that control this:

 --use-memcached (defaults to "no")
 --memcached-servers "host1:port1,..." (defaults to '127.0.0.1:11211')
 --memcached-prefix "desired_namespace prefix" (defaults to 'koha_')

It respects the current schema configuration schema, where configuration
values are pondered like this:

hardcoded < koha-sites.conf < koha-create option switches

koha-sites.conf is read for USE_MEMCACHED, MEMCACHED_SERVERS and
MEMCACHED_PREFIX.

Note: the docs discourage setting user's own namespace prefix.

Using memcached is off as the default. The relevant configuration
variables will remain empty if the user doesn't pass --use-memcached
to the command. It matches the current behaviour.

To test:
- Apply the patch
- Build your own packages and install them on a test server
a) Create a new instance without using the new switches like:
 $ koha-create --create-db memctest
 - Check that /etc/koha/sites/memctest/koha-conf.xml contains:
   * Empty <memcached_servers> tag.
   * Empty <memcached_namespace> tag.

b) Play with the possible combination of option switches
(Note that the code defaults to empty and will remain like that if
--use-memcached is not used, so less tests...)

 $ koha-create --create-db --use-memcached memctest
 $ koha-create --create-db --use-memcached --memcached-servers "anything:xxx" memctest
 $ koha-create --create-db --use-memcached --memcached-servers "anything:xxx" --memcached-prefix "something" memctest
 $ koha-create --create-db --use-memcached --memcached-prefix "something" memctest

 - Check the koha-conf.xml and /etc/apache2/sites-enabled/memctest
   file reflect the chosen options.

c) Run
 $ koha-create --help
 - It should advertise this addition accordingly.

d) Run
 $ man koha-create
 - Man page for koha-create should provide good information on the new
   switches behaviour

Sponsored-by: Universidad Nacional de Cordoba
Signed-off-by: Mark Tompsett <mtompset@hotmail.com>
Signed-off-by: Robin Sheat <robin@catalyst.net.nz>
Signed-off-by: Galen Charlton <gmc@esilibrary.com>
2013-10-30 03:27:51 +00:00

329 lines
14 KiB
XML
Raw Blame History

<article xmlns='http://docbook.org/ns/docbook'>
<title>koha-create</title>
<info>
<productname>Koha</productname> is the first free software library automation package.
<author>
<orgname>The Koha Community</orgname>
<uri>http://koha-community.org/</uri>
</author>
</info>
<refentry xml:id="koha-create">
<refmeta>
<refentrytitle>koha-create</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>koha-create</refname>
<refpurpose>Create a new Koha instance.</refpurpose>
<refclass>UNIX/Linux</refclass>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>koha-create</command>
<arg choice="req"><option>--create-db</option>|<option>--request-db</option>|<option>--populate-db</option>|<option>--use-db</option></arg>
<arg><option>--marcflavor</option> marc21|normarc|unimarc</arg>
<arg><option>--zebralang</option> en|es|fr|nb|ru|uk</arg>
<arg><option>--auth-idx</option> dom|grs1</arg>
<arg><option>--biblio-idx</option> dom|grs1</arg>
<arg><option>--use-memcached</option></arg>
<arg><option>--memcached-servers</option> server:port</arg>
<arg><option>--memcached-prefix</option> namespace_prefix</arg>
<arg><option>--defaultsql</option> /path/to/some.sql</arg>
<arg><option>--configfile</option> /path/to/config</arg>
<arg><option>--passwdfile</option> /path/to/passwd</arg>
<arg><option>--database</option> database</arg>
<arg><option>--adminuser</option> n</arg>
<arg choice="req" rep="norepeat"><replaceable>instancename</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--create-db</option></term>
<listitem>
<para>Create a new database on localhost. If the database you want to use does not reside on localhost, you can use <option>--request-db</option> and <option>--populate-db</option>, see below. If the database already exists, you can use <option>--use-db</option>, see below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--request-db</option></term>
<listitem>
<para>This option will create a file called <filename>instancename-db-request.txt</filename> in your current directory that contains information about how the database needs to be set up.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--populate-db</option></term>
<listitem>
<para>When you have run koha-create with the <option>--request-db</option> option, and a database has been set up, you can finish your installation by running <command>koha-create</command> with this option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-db</option></term>
<listitem>
<para>When the database you want to use has already been populated, you can run <command>koha-create</command> with this option to take care of all the other set-up configuration.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--configfile</option></term>
<listitem>
<para>Path to an alternative config file. This file can hold the same variables as the default config file, see below for details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--database</option></term>
<listitem>
<para>MySQL database to use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--defaultsql</option></term>
<listitem>
<para>Path to an SQL-file other than the one pointed to in the default or alternative config file. Corresponds to the DEFAULTSQL config file variable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--marcflavor</option></term>
<listitem>
<para>Specifies format of MARC records to be indexed by Zebra. Corresponds to the ZEBRA_MARC_FORMAT config file variable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--passwdfile</option></term>
<listitem>
<para>Path to an alternative passwd file. This file is in the same format as the default (Koha) passwd file, see below for details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--zebralang</option></term>
<listitem>
<para>Primary language for Zebra indexing. Corresponds to the ZEBRA_LANGUAGE config file variable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--auth-idx</option></term>
<listitem>
<para>Specified the desired indexing mode for authority records. Valid options are <option>dom</option> (default) and <option>grs1</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--biblio-idx</option></term>
<listitem>
<para>Specified the desired indexing mode for bibliographic records. Valid options are <option>dom</option> (default) and <option>grs1</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--use-memcached</option></term>
<listitem>
<para>Make the Koha instance use memcached. <option>Disabled by default</option>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--memcached-servers</option></term>
<listitem>
<para>Specify a comma-separated list of host:port memcached servers for using with the created Koha instance. Defaults to <option>127.0.0.1:11211</option>, the needed configuration for a locally installed memcached server.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--memcached-prefix</option></term>
<listitem>
<para>Specifiy a <option>namespace prefix</option> for memcached. You usually leave this option alone to avoid namespace collisions. It defaults to <option>koha_</option>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Description</title>
<para><command>koha-create</command> creates a new Koha instance. It is meant for a site that provides Koha hosting, and serves several sites from the same host.</para>
<para>The name of the instance is used as the domain name for Apache, Unix user and group names, and MySQL username and database names are derived from it. Unix user and group are named instance-koha. MySQL username is koha_instance, and database is koha_instance.</para>
<para>The Unix user has logins disabled. The password for MySQL is generated randomly, and printed to the terminal.</para>
<para>The instance name is used as the domain name (ServerName) for Apache. The public catalogue (OPAC), for library customers, is on port 80. The staff client interface is configured similarly, depending on the settings in <filename>/etc/koha/koha-sites.conf</filename> or alternate config file.</para>
<para>After the Koha instance is created, it is ready to be used, but the librarian needs to log in via the intranet and configure things.</para>
<para>Several configuration variables are available for adjusting this behavior. The variables are put into <filename>/etc/koha/koha-sites.conf</filename>. The following variables are obeyed:</para>
<variablelist>
<varlistentry>
<term><option>DOMAIN</option></term>
<listitem>
<para>The domain to append to the instance name, for Apache ServerName. Default is empty. The value must begin with a period.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>OPACPORT</option></term>
<listitem>
<para>The port for the OPAC.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>OPACPREFIX</option></term>
<listitem>
<para>This is inserted before the instance name when forming Apache ServerName. For subdomains, make sure it ends with a period.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>OPACSUFFIX</option></term>
<listitem>
<para>This is inserted after the instance name, but before the domain name, when forming Apache ServerName.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>INTRAPORT</option></term>
<listitem>
<para>The port for the intranet. If you set this to empty or 80, then you must also define INTRAPREFIX or INTRASUFFIX.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>INTRAPREFIX</option></term>
<listitem>
<para>This is inserted before the instance name when forming Apache ServerName. For subdomains, make sure it ends with a period.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>INTRASUFFIX</option></term>
<listitem>
<para>This is inserted after the instance name, but before the domain name, when forming Apache ServerName.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>DEFAULTSQL</option></term>
<listitem>
<para>An SQL file (compressed with gzip) that can be fed to mysql(1) to initialize the database after it has been created. Might be created using koha-dump-defaults(8).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>USE_MEMCACHED</option></term>
<listitem>
<para>Valid values are <option>yes</option> and <option>no</option>. If not present koha-create will default to <option>no</option>. Also, this will be overriden by the <option>--use-memcached</option> switch.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>MEMCACHED_SERVERS</option></term>
<listitem>
<para>A comma-separated list of valid memcached servers. Usually in the form of <option>host:port</option>. If not present koha-create will default to <option>127.0.0.1:11211</option>. Also, this will be overriden by the arguments of the <option>--memcached-servers</option> switch.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>MEMCACHED_PREFIX</option></term>
<listitem>
<para>A prefix for all new Koha instances to use in memcached. If not present koha-create will default to <option>koha_</option>. Also, this will be overriden by the arguments of the <option>--memcached-prefix</option> switch.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>ZEBRA_MARC_FORMAT</option></term>
<listitem>
<para>Specifies format of MARC records to be indexed by Zebra. Possible values are 'marc21', 'normarc' and 'unimarc'.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>ZEBRA_LANGUAGE</option></term>
<listitem>
<para>Primary language for Zebra indexing. Possible values are 'en', 'es', 'fr', 'nb', 'ru' and 'uk'.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Order of precedence for config options, from lowest to highest:</para>
<orderedlist>
<listitem><para>The defaults set in the code of <command>koha-create</command></para></listitem>
<listitem><para><filename>/etc/koha/koha-sites.conf</filename></para></listitem>
<listitem><para>Config file specified with <option>--configfile</option></para></listitem>
<listitem><para>Individual command line options</para></listitem>
</orderedlist>
</refsect1>
<refsect1><title>Files</title>
<variablelist>
<varlistentry>
<term><option><filename>/etc/koha/koha-sites.conf</filename></option></term>
<listitem>
<para>Configuration variables are read from this file, if it exists.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option><filename>/etc/koha/passwd</filename></option></term>
<listitem>
<para>Pre-selected database credentials are read from this file, if it exists. The format for this file is instancename:username:passwd:database. Database is optional, but the other three are required if you want to use pre-determined database user credentials.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Bugs</title>
<para>The program is a bit fragile. If something goes wrong, it does not clean up after itself.</para>
<para>Bugs can be reported here: <uri>http://bugs.koha-community.org/bugzilla3/</uri></para>
</refsect1>
<refsect1><title>Example</title>
<para>To create a new Koha instance:</para>
<para><command>koha-create --create-db hslibrary</command></para>
<para>The public catalog is now at <uri>http://hslibrary/</uri> and the librarian interface at <uri>http://hslibrary:8080/</uri>.</para>
<para>To use full domain names, and have the intranet interface on port 80, but on a different domain name, add the following variables to the configuration file:</para>
<itemizedlist spacing="compact">
<listitem><para>DOMAIN=".example.com"</para></listitem>
<listitem><para>INTRAPORT=""</para></listitem>
<listitem><para>INTRASUFFIX="-intra"</para></listitem>
</itemizedlist>
<para>This will result in the addresses for the public and intranet interfaces becoming these:</para>
<itemizedlist spacing="compact">
<listitem><para><uri>http://hslibrary.example.com/</uri></para></listitem>
<listitem><para><uri>http://hslibrary-intra.example.com/</uri></para></listitem>
</itemizedlist>
<para>Configuration changes only apply to instances created afterwards.</para>
</refsect1>
<refsect1><title>See also</title>
<simplelist type="inline">
<member><command>koha-remove(8)</command></member>
</simplelist>
</refsect1>
</refentry>
</article>
View git blame Copy permalink