debian/docs/koha-create.xml

   1 <article xmlns='http://docbook.org/ns/docbook'>
   2 <title>koha-create</title>
   3 <info>
   4 <productname>Koha</productname> is the first free software library automation package.
   5 <author>
   6   <orgname>The Koha Communnity</orgname>
   7   <uri>http://koha-community.org/</uri>
   8 </author>
   9 </info>
  10
  11 <refentry xml:id="koha-create">
  12
  13   <refmeta>
  14     <refentrytitle>koha-create</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>koha-create</refname>
  20     <refpurpose>Create a new Koha instance.</refpurpose>
  21     <refclass>UNIX/Linux</refclass>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>koha-create</command>
  27       <arg><option>--create-db</option>|<option>--request-db</option>|<option>--populate-db</option></arg>
  28       <arg><option>--marcflavor</option> marc21|normarc|unimarc</arg>
  29       <arg><option>--zebralang</option> en|nb|fr</arg>
  30       <arg><option>--defaultsql</option> /path/to/some.sql</arg>
  31       <arg><option>--configfile</option> /path/to/config</arg>
  32       <arg><option>--adminuser</option> n</arg>
  33       <arg choice="req" rep="norepeat"><replaceable>instancename</replaceable></arg>
  34     </cmdsynopsis>
  35   </refsynopsisdiv>
  36
  37   <refsect1><title>Options</title>
  38   <variablelist>
  39
  40     <varlistentry>
  41       <term><option>--create-db</option></term>
  42       <listitem>
  43         <para>Create a new datbase 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.</para>
  44       </listitem>
  45     </varlistentry>
  46
  47     <varlistentry>
  48       <term><option>--request-db</option></term>
  49       <listitem>
  50         <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>
  51       </listitem>
  52     </varlistentry>
  53
  54     <varlistentry>
  55       <term><option>--populate-db</option></term>
  56       <listitem>
  57         <para>When you have run koha-create with the <option>--request-db</option> option, and a database has been set up, you can finnish your installation by running <command>koha-create</command> with this option.</para>
  58       </listitem>
  59     </varlistentry>
  60
  61     <varlistentry>
  62       <term><option>--configfile</option></term>
  63       <listitem>
  64         <para>Path to an alternative config file. This file can hold the same variables as the default config file, see below for details.</para>
  65       </listitem>
  66     </varlistentry>
  67
  68     <varlistentry>
  69       <term><option>--defaultsql</option></term>
  70       <listitem>
  71         <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>
  72       </listitem>
  73     </varlistentry>
  74
  75     <varlistentry>
  76       <term><option>--marcflavor</option></term>
  77       <listitem>
  78         <para>Specifies format of MARC records to be indexed by Zebra. Corresponds to the ZEBRA_MARC_FORMAT config file variable.</para>
  79       </listitem>
  80     </varlistentry>
  81
  82     <varlistentry>
  83       <term><option>--zebralang</option></term>
  84       <listitem>
  85         <para>Primary language for Zebra indexing. Corresponds to the ZEBRA_LANGUAGE config file variable.</para>
  86       </listitem>
  87     </varlistentry>
  88
  89   </variablelist>
  90   </refsect1>
  91
  92   <refsect1><title>Description</title>
  93     <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>
  94     <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>
  95     <para>The Unix user has logins disabled.  The password for MySQL is generated randomly, and printed to the terminal.</para>
  96     <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>
  97     <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>
  98     <para>Several configuration variables are available for adjusting this behavior. The variables are put into <filename>/etc/koha/koha-site.conf</filename>. The following variables are obeyed:</para>
  99
 100     <variablelist>
 101
 102       <varlistentry>
 103         <term><option>DOMAIN</option></term>
 104         <listitem>
 105           <para>The domain to append to the instance name, for Apache ServerName. Default is empty. The value must begin with a period.</para>
 106         </listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><option>INTRAPORT</option></term>
 111         <listitem>
 112           <para>The port for the intranet.  If you set this to empty or 80, then you must also define INTRAPREFIX or INTRASUFFIX.</para>
 113         </listitem>
 114       </varlistentry>
 115
 116       <varlistentry>
 117         <term><option>INTRAPREFIX</option></term>
 118         <listitem>
 119           <para>This is inserted before the instance name  when  forming  Apache ServerName.  For subdomains, make sure it ends with a period.</para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><option>INTRASUFFIX</option></term>
 125         <listitem>
 126           <para>This  is inserted after the instance name, but before the domain name, when forming Apache ServerName.</para>
 127         </listitem>
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><option>DEFAULTSQL</option></term>
 132         <listitem>
 133           <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>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term><option>ZEBRA_MARC_FORMAT</option></term>
 139         <listitem>
 140           <para>Specifies format of MARC records to be indexed by Zebra.  Possible values are 'marc21', 'normarc' and 'unimarc'.</para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><option>ZEBRA_LANGUAGE</option></term>
 146         <listitem>
 147           <para>Primary  language  for Zebra indexing. Possible values are 'en', 'fr' and 'nb'.</para>
 148         </listitem>
 149       </varlistentry>
 150
 151     </variablelist>
 152
 153     <para>Order of precedence for config options, from lowest to highest:</para>
 154
 155     <orderedlist>
 156       <listitem><para>The defaults set in the code of <command>koha-create</command></para></listitem>
 157       <listitem><para><filename>/etc/koha/koha-sites.conf</filename></para></listitem>
 158       <listitem><para>Config file specified with <option>--configfile</option></para></listitem>
 159       <listitem><para>Individual command line options</para></listitem>
 160     </orderedlist>
 161
 162   </refsect1>
 163
 164   <refsect1><title>Files</title>
 165   <variablelist>
 166     <varlistentry>
 167       <term><option><filename>/etc/koha/koha-sites.conf</filename></option></term>
 168       <listitem>
 169         <para>Configuration variables are read from this file, if it exists.</para>
 170       </listitem>
 171     </varlistentry>
 172   </variablelist>
 173   </refsect1>
 174
 175   <refsect1><title>Bugs</title>
 176   <para>The program is a bit fragile. If something goes wrong, it does not clean up after itself.</para>
 177   <para>Bugs can be reported here: <uri>http://bugs.koha-community.org/bugzilla3/</uri></para>
 178   </refsect1>
 179
 180   <refsect1><title>Example</title>
 181
 182     <para>To create a new Koha instance:</para>
 183
 184     <para><command>koha-create hslibrary</command></para>
 185
 186     <para>The public catalog is now at <uri>http://hslibrary/</uri> and the librarian interface at <uri>http://hslibrary:8080/</uri>.</para>
 187
 188     <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>
 189
 190     <itemizedlist spacing="compact">
 191       <listitem><para>DOMAIN=".example.com"</para></listitem>
 192       <listitem><para>INTRAPORT=""</para></listitem>
 193       <listitem><para>INTRASUFFIX="-intra"</para></listitem>
 194     </itemizedlist>
 195
 196     <para>This will result in the addresses for the public and intranet interfaces becoming these:</para>
 197
 198     <itemizedlist spacing="compact">
 199       <listitem><para><uri>http://hslibrary.example.com/</uri></para></listitem>
 200       <listitem><para><uri>http://hslibrary-intra.example.com/</uri></para></listitem>
 201     </itemizedlist>
 202     <para>Configuration changes only apply to instances created afterwards.</para>
 203
 204   </refsect1>
 205
 206   <refsect1><title>See also</title>
 207
 208   <simplelist type="inline">
 209     <member><command>koha-remove(8)</command></member>
 210   </simplelist>
 211
 212   </refsect1>
 213
 214 </refentry>
 215
 216 </article>