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 Community</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 choice="req"><option>--create-db</option>|<option>--request-db</option>|<option>--populate-db</option>|<option>--use-db</option></arg>
  28       <arg><option>--marcflavor</option> marc21|normarc|unimarc</arg>
  29       <arg><option>--zebralang</option> el|en|es|fr|nb|ru|uk</arg>
  30       <arg><option>--memcached-servers</option> server:port</arg>
  31       <arg><option>--memcached-prefix</option> namespace_prefix</arg>
  32       <arg><option>--elasticsearch-server</option> server:port</arg>
  33       <arg><option>--defaultsql</option> /path/to/some.sql</arg>
  34       <arg><option>--configfile</option> /path/to/config</arg>
  35       <arg><option>--passwdfile</option> /path/to/passwd</arg>
  36       <arg><option>--dbhost</option> host</arg>
  37       <arg><option>--database</option> database</arg>
  38       <arg><option>--adminuser</option> n</arg>
  39       <arg><option>--enable-sru</option></arg>
  40       <arg><option>--sru-port</option> port</arg>
  41       <arg><option>--template-cache-dir</option> directory</arg>
  42       <arg><option>--timezone</option> time/zone</arg>
  43       <arg><option>--upload-path</option> directory</arg>
  44       <arg><option>--tmp-path</option> directory</arg>
  45       <arg><option>--letsencrypt</option></arg>
  46       <arg><option>--smtp-host</option> host</arg>
  47       <arg><option>--smtp-port</option> port</arg>
  48       <arg><option>--smtp-timeout</option> n</arg>
  49       <arg><option>--smtp-ssl-mode</option> disabled|ssl|starttls</arg>
  50       <arg><option>--smtp-user-name</option> user</arg>
  51       <arg><option>--smtp-password</option>  pass</arg>
  52       <arg><option>--smtp-debug</option></arg>
  53       <arg><option>--help</option>|<option>-h</option></arg>
  54
  55       <arg choice="req" rep="norepeat"><replaceable>instancename</replaceable></arg>
  56     </cmdsynopsis>
  57   </refsynopsisdiv>
  58
  59   <refsect1><title>Options</title>
  60   <variablelist>
  61
  62     <varlistentry>
  63       <term><option>--create-db</option></term>
  64       <listitem>
  65         <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>
  66       </listitem>
  67     </varlistentry>
  68
  69     <varlistentry>
  70       <term><option>--request-db</option></term>
  71       <listitem>
  72         <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>
  73       </listitem>
  74     </varlistentry>
  75
  76     <varlistentry>
  77       <term><option>--populate-db</option></term>
  78       <listitem>
  79         <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>
  80       </listitem>
  81     </varlistentry>
  82
  83     <varlistentry>
  84       <term><option>--use-db</option></term>
  85       <listitem>
  86         <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>
  87       </listitem>
  88     </varlistentry>
  89
  90     <varlistentry>
  91       <term><option>--configfile</option></term>
  92       <listitem>
  93         <para>Path to an alternative config file. This file can hold the same variables as the default config file, see below for details.</para>
  94       </listitem>
  95     </varlistentry>
  96
  97     <varlistentry>
  98       <term><option>--database</option></term>
  99       <listitem>
 100         <para>MySQL database to use.</para>
 101       </listitem>
 102     </varlistentry>
 103
 104     <varlistentry>
 105       <term><option>--dbhost</option></term>
 106       <listitem>
 107         <para>Database server hostname/IP to use.</para>
 108       </listitem>
 109     </varlistentry>
 110
 111     <varlistentry>
 112       <term><option>--defaultsql</option></term>
 113       <listitem>
 114         <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>
 115       </listitem>
 116     </varlistentry>
 117
 118     <varlistentry>
 119       <term><option>--adminuser</option></term>
 120       <listitem>
 121         <para>Specify the borrowernumber of the user that should have a new, random password set as part of setting up the new instance. The password will be reported as part of the output of the current script. If --adminuser is not specified, the user with borrowernumber = 1 will be updated. If an SQL file is not used to populate the database of the newly created instance, no admin user will be created.</para>
 122       </listitem>
 123     </varlistentry>
 124
 125     <varlistentry>
 126       <term><option>--marcflavor</option></term>
 127       <listitem>
 128         <para>Specifies format of MARC records to be indexed by Zebra. Corresponds to the ZEBRA_MARC_FORMAT config file variable.</para>
 129       </listitem>
 130     </varlistentry>
 131
 132     <varlistentry>
 133       <term><option>--passwdfile</option></term>
 134       <listitem>
 135         <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>
 136       </listitem>
 137     </varlistentry>
 138
 139     <varlistentry>
 140       <term><option>--zebralang</option></term>
 141       <listitem>
 142         <para>Primary language for Zebra indexing. Corresponds to the ZEBRA_LANGUAGE config file variable.</para>
 143       </listitem>
 144     </varlistentry>
 145
 146     <varlistentry>
 147       <term><option>--memcached-servers</option></term>
 148       <listitem>
 149         <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>
 150       </listitem>
 151     </varlistentry>
 152
 153     <varlistentry>
 154       <term><option>--memcached-prefix</option></term>
 155       <listitem>
 156         <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>
 157       </listitem>
 158     </varlistentry>
 159
 160     <varlistentry>
 161       <term><option>--elasticsearch-server</option></term>
 162       <listitem>
 163         <para>Specifiy a <option>server:port</option> Elasticsearch server configuration. It defaults to <option>localhost:9200</option>.</para>
 164       </listitem>
 165     </varlistentry>
 166
 167     <varlistentry>
 168       <term><option>--enable-sru</option></term>
 169       <listitem>
 170         <para>Enable the Z39.50/SRU server for the created instance.</para>
 171       </listitem>
 172     </varlistentry>
 173
 174     <varlistentry>
 175       <term><option>--sru-port</option></term>
 176       <listitem>
 177         <para>Specifiy a <option> TCP port number</option> for the Z39.50/SRU server to listen on.</para>
 178       </listitem>
 179     </varlistentry>
 180
 181     <varlistentry>
 182       <term><option>--template-cache-dir</option></term>
 183       <listitem>
 184         <para>Specify a <option>directory</option> for storing the template cache files of the instance.
 185               It defaults to <filename>/var/cache/koha/instance/templates</filename>.</para>
 186       </listitem>
 187     </varlistentry>
 188
 189     <varlistentry>
 190       <term><option>--timezone</option></term>
 191       <listitem>
 192         <para>Specify a <option>timezone</option> for the created instance. e.g. America/Argentina</para>
 193       </listitem>
 194     </varlistentry>
 195
 196     <varlistentry>
 197       <term><option>--upload-path</option></term>
 198       <listitem>
 199         <para>Specify a <option>directory</option> for storing the permanently uploaded files of the instance.
 200               It defaults to <filename>/var/lib/koha/instance/uploads</filename>.</para>
 201       </listitem>
 202     </varlistentry>
 203
 204     <varlistentry>
 205       <term><option>--tmp-path</option></term>
 206       <listitem>
 207         <para>Specify a <option>directory</option> for storing the temporary files. For example temporarily
 208               uploaded files of the instance. It defaults to <filename>/var/lib/koha/instance/tmp</filename>.</para>
 209       </listitem>
 210     </varlistentry>
 211
 212     <varlistentry>
 213       <term><option>--letsencrypt</option></term>
 214       <listitem>
 215         <para>Set up a https-only website with letsencrypt certificates</para>
 216       </listitem>
 217     </varlistentry>
 218
 219     <varlistentry>
 220       <term><option>--smtp-host</option></term>
 221       <listitem>
 222         <para>Specify the SMTP server <option>hostname</option>. (default: localhost)</para>
 223       </listitem>
 224     </varlistentry>
 225
 226     <varlistentry>
 227       <term><option>--smtp-port</option></term>
 228       <listitem>
 229         <para>Specify the SMTP server <option>port</option>. (default: 25)</para>
 230       </listitem>
 231     </varlistentry>
 232
 233     <varlistentry>
 234       <term><option>--smtp-timeout</option></term>
 235       <listitem>
 236         <para>Timeout for outbound SMTP connections. (default: 120)</para>
 237       </listitem>
 238     </varlistentry>
 239
 240     <varlistentry>
 241       <term><option>--smtp-ssl-mode</option></term>
 242       <listitem>
 243         <para>Set the SSL mode. Options are <option>disabled</option> (default), <option>ssl</option> and <option>starttls</option>.</para>
 244       </listitem>
 245     </varlistentry>
 246
 247     <varlistentry>
 248       <term><option>--smtp-user-name</option></term>
 249       <listitem>
 250         <para>Specify the user name to use for SMTP. (default: empty)</para>
 251       </listitem>
 252     </varlistentry>
 253
 254     <varlistentry>
 255       <term><option>--smtp-password</option></term>
 256       <listitem>
 257         <para>Specify the password for SMTP. (default: empty)</para>
 258       </listitem>
 259     </varlistentry>
 260
 261     <varlistentry>
 262       <term><option>--smtp-debug</option></term>
 263       <listitem>
 264         <para>Enable debug mode.</para>
 265       </listitem>
 266     </varlistentry>
 267
 268     <varlistentry>
 269       <term><option>--help</option>,<option>-h</option></term>
 270       <listitem>
 271         <para>Print usage information.</para>
 272       </listitem>
 273     </varlistentry>
 274
 275
 276   </variablelist>
 277   </refsect1>
 278
 279   <refsect1><title>Description</title>
 280     <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>
 281     <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>
 282     <para>The Unix user has logins disabled.  The password for MySQL is generated randomly, and printed to the terminal.</para>
 283     <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 interface is configured similarly, depending on the settings in <filename>/etc/koha/koha-sites.conf</filename> or alternate config file.</para>
 284     <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>
 285     <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>
 286
 287     <variablelist>
 288
 289       <varlistentry>
 290         <term><option>DOMAIN</option></term>
 291         <listitem>
 292           <para>The domain to append to the instance name, for Apache ServerName. Default is empty. The value must begin with a period.</para>
 293         </listitem>
 294       </varlistentry>
 295
 296       <varlistentry>
 297         <term><option>OPACPORT</option></term>
 298         <listitem>
 299           <para>The port for the OPAC.</para>
 300         </listitem>
 301       </varlistentry>
 302
 303       <varlistentry>
 304         <term><option>OPACPREFIX</option></term>
 305         <listitem>
 306           <para>This is inserted before the instance name  when  forming  Apache ServerName.  For subdomains, make sure it ends with a period.</para>
 307         </listitem>
 308       </varlistentry>
 309
 310       <varlistentry>
 311         <term><option>OPACSUFFIX</option></term>
 312         <listitem>
 313           <para>This  is inserted after the instance name, but before the domain name, when forming Apache ServerName.</para>
 314         </listitem>
 315       </varlistentry>
 316
 317       <varlistentry>
 318         <term><option>INTRAPORT</option></term>
 319         <listitem>
 320           <para>The port for the intranet.  If you set this to empty or 80, then you must also define INTRAPREFIX or INTRASUFFIX.</para>
 321         </listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term><option>INTRAPREFIX</option></term>
 326         <listitem>
 327           <para>This is inserted before the instance name  when  forming  Apache ServerName.  For subdomains, make sure it ends with a period.</para>
 328         </listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <term><option>INTRASUFFIX</option></term>
 333         <listitem>
 334           <para>This  is inserted after the instance name, but before the domain name, when forming Apache ServerName.</para>
 335         </listitem>
 336       </varlistentry>
 337
 338       <varlistentry>
 339         <term><option>DEFAULTSQL</option></term>
 340         <listitem>
 341           <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>
 342           <para>If the SQL file contains users, the user with borrowernumber = 1 will have a new, random password set. This password will be reported in the output of the script. If another user than borrowernumber 1 should have its password set, the borrowernumber of this user can be set with the --adminuser command line option.</para>
 343         </listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term><option>MEMCACHED_SERVERS</option></term>
 348         <listitem>
 349           <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>
 350         </listitem>
 351       </varlistentry>
 352
 353       <varlistentry>
 354         <term><option>MEMCACHED_PREFIX</option></term>
 355         <listitem>
 356           <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>
 357         </listitem>
 358       </varlistentry>
 359
 360
 361       <varlistentry>
 362         <term><option>ZEBRA_MARC_FORMAT</option></term>
 363         <listitem>
 364           <para>Specifies format of MARC records to be indexed by Zebra.  Possible values are 'marc21', 'normarc' and 'unimarc'.</para>
 365         </listitem>
 366       </varlistentry>
 367
 368       <varlistentry>
 369         <term><option>ZEBRA_LANGUAGE</option></term>
 370         <listitem>
 371           <para>Primary  language  for Zebra indexing. Possible values are 'en', 'es', 'fr', 'nb', 'ru' and 'uk'.</para>
 372         </listitem>
 373       </varlistentry>
 374
 375     </variablelist>
 376
 377     <para>Order of precedence for config options, from lowest to highest:</para>
 378
 379     <orderedlist>
 380       <listitem><para>The defaults set in the code of <command>koha-create</command></para></listitem>
 381       <listitem><para><filename>/etc/koha/koha-sites.conf</filename></para></listitem>
 382       <listitem><para>Config file specified with <option>--configfile</option></para></listitem>
 383       <listitem><para>Individual command line options</para></listitem>
 384     </orderedlist>
 385
 386   </refsect1>
 387
 388   <refsect1><title>Files</title>
 389   <variablelist>
 390     <varlistentry>
 391       <term><option><filename>/etc/koha/koha-sites.conf</filename></option></term>
 392       <listitem>
 393         <para>Configuration variables are read from this file, if it exists.</para>
 394       </listitem>
 395     </varlistentry>
 396
 397     <varlistentry>
 398       <term><option><filename>/etc/koha/passwd</filename></option></term>
 399       <listitem>
 400         <para>Pre-selected database credentials are read from this file, if it exists. The format for this file is instancename:username:passwd:database:dbhost. Database is optional, but the other three are required if you want to use pre-determined database user credentials.</para>
 401       </listitem>
 402     </varlistentry>
 403   </variablelist>
 404   </refsect1>
 405
 406   <refsect1><title>Bugs</title>
 407   <para>The program is a bit fragile. If something goes wrong, it does not clean up after itself.</para>
 408   <para>Bugs can be reported here: <uri>http://bugs.koha-community.org/bugzilla3/</uri></para>
 409   </refsect1>
 410
 411   <refsect1><title>Example</title>
 412
 413     <para>To create a new Koha instance:</para>
 414
 415     <para><command>koha-create --create-db hslibrary</command></para>
 416
 417     <para>The public catalog is now at <uri>http://hslibrary/</uri> and the librarian interface at <uri>http://hslibrary:8080/</uri>.</para>
 418
 419     <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>
 420
 421     <itemizedlist spacing="compact">
 422       <listitem><para>DOMAIN=".example.com"</para></listitem>
 423       <listitem><para>INTRAPORT=""</para></listitem>
 424       <listitem><para>INTRASUFFIX="-intra"</para></listitem>
 425     </itemizedlist>
 426
 427     <para>This will result in the addresses for the public and intranet interfaces becoming these:</para>
 428
 429     <itemizedlist spacing="compact">
 430       <listitem><para><uri>http://hslibrary.example.com/</uri></para></listitem>
 431       <listitem><para><uri>http://hslibrary-intra.example.com/</uri></para></listitem>
 432     </itemizedlist>
 433     <para>Configuration changes only apply to instances created afterwards.</para>
 434
 435   </refsect1>
 436
 437   <refsect1><title>See also</title>
 438
 439   <simplelist type="inline">
 440     <member><command>koha-remove(8)</command></member>
 441   </simplelist>
 442
 443   </refsect1>
 444
 445 </refentry>
 446
 447 </article>