[Koha-cvs] CVS: koha-doc/en/sysadmin/maintenance Updating_Koha.xml,NONE,1.1 Backups_and_Restoring.xml,NONE,1.1
skemotah
shedges at users.sourceforge.net
Fri Dec 24 16:45:01 CET 2004
Update of /cvsroot/koha/koha-doc/en/sysadmin/maintenance
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv24611
Added Files:
Updating_Koha.xml Backups_and_Restoring.xml
Log Message:
Load original version
--- NEW FILE ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<title>Updating Koha</title>
<articleinfo>
<pubdate>2004-12-15</pubdate>
<author>
<firstname>Joshua</firstname>
<surname>Ferraro</surname>
<email>jmf at kados dot org</email>
</author>
<revhistory>
<revision>
<revnumber>2.2.0</revnumber>
<date>2004-12-13</date>
<authorinitials>jmf</authorinitials>
<revdescription>
<para>Changes made by Joshua Ferraro. Original Document</para>
</revdescription>
</revision>
</revhistory>
</articleinfo>
<para>TO DO:</para>
<itemizedlist>
<listitem>
<para>Add information on keeping Koha up-to-date using Arch</para>
</listitem>
<listitem>
<para>Add information on upgrading Koha from version to version</para>
</listitem>
</itemizedlist>
<section>
<title>Using this document</title>
<section>
<title id="copyright">Copyright and License</title>
<para>Copyright 2004 Joshua Ferraro <email>jmf at kados dot
org</email></para>
<para>This document is related to Koha and is licensed to you under the
GNU General Public License version 2 or later (<ulink
url="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</ulink>).
Koha-related documents may be reproduced and distributed in whole or in
part, in any medium physical or electronic, as long as this copyright
notice is retained on all copies.</para>
<para>You may create a derivative work and distribute it provided that
you: <orderedlist>
<listitem>
<para>License the derivative work with this same license, or the
Linux Documentation Project License (<ulink
url="http://www.tldp.org/COPYRIGHT.html">http://www.tldp.org/COPYRIGHT.html</ulink>).
Include a copyright notice and at least a pointer to the license
used.</para>
</listitem>
<listitem>
<para>Give due credit to previous authors and major
contributors.</para>
</listitem>
</orderedlist></para>
<para>Commercial redistribution is allowed and encouraged; however, the
author would like to be notified of any such distributions.</para>
</section>
<section>
<title id="disclaimer">Disclaimer</title>
<para>No liability for the contents of this document can be accepted.
Use the concepts, examples and information at your own risk. There may
be errors and inaccuracies, that could be damaging to your system.
Proceed with caution, and although this is highly unlikely, the
author(s) do not take any responsibility.</para>
<para>All copyrights are held by their by their respective owners,
unless specifically noted otherwise. Use of a term in this document
should not be regarded as affecting the validity of any trademark or
service mark. Naming of particular products or brands should not be seen
as endorsements.</para>
</section>
</section>
<section>
<title>Introduction</title>
<para>Since the beginning of the project, <application>Koha</application>
project developers have used <systemitem>sourceforge.net</systemitem> as
their centralized repository for source code. Sourceforge's repositories
use <firstterm>CVS</firstterm> (Concurrent Versions System), a tool used
to manage changes within a source code tree. Recently, some in the
community have expressed interest in migrating Revision Management Systems
(RMS) from CVS to a more distributed system (<firstterm>Arch</firstterm>)
and as a result <application>Koha</application> 2.0 is now maintained
using Arch. I hope to include a discussion of keeping a
<application>Koha</application> 2.0 system up-to-date using Arch in this
guide someday (maybe someone who has actually done so would be willing to
write that section) and certainly if project developers move all
<application>Koha</application> development to an Arch model such a guide
would be necessary, but for now, I can describe the basics of how to keep
your <application>Koha</application> 2.2 system up-to-date using CVS and
SourceForge. At this time, this document does not discuss how to upgrade a
system from an older version of <application>Koha</application> to a newer
version.</para>
</section>
<section>
<title>Before You Begin</title>
<para>In order to access a CVS repository, you must first install a CVS
client (if one is not already installed on your system). Information about
CVS client software and it's use with
<systemitem>sourceforge.net</systemitem> can be found may be found in the
following SourceForge.net document: <ulink
url="http://sourceforge.net/docman/display_doc.php?docid=14033&group_id=1">Basic
Introduction to CVS and SourceForge.net (SF.net) Project CVS
Services</ulink>.</para>
<section>
<title>Understand What You Will Be Doing</title>
<para>If you are unfamiliar with the concept of symlinks take a look at
this helpful introduction: <ulink
url="http://librenix.com/?inode=5164">http://librenix.com/?inode=5164</ulink>.
You will be "checking out" a <application>Koha</application> CVS
repository and then symlinking your installed
<application>Koha</application> directory tree to the CVS repository
which will enable you to update to the latest stable version of
<application>Koha</application> by issuing a simple CVS update
command.</para>
<para>The resulting directory structure will also afford you an easy
centralized backup point for your <application>Koha</application>
directory tree -- you should make sure to regularly backup your database
and <application>Koha</application> directory tree to preserve your data
as well as any customizations you've made to
<application>Koha</application> templates, modules or scripts. More info
on backing up your <application>Koha</application> system can be found
in that section of the <application>Koha</application> documentation.
For now, choose a location that is easy for you to remember. I have a
directory <filename>/build</filename> on a separate partition that I use
as the root directory for my <application>Koha</application>
installation as well as custom library-specific scripts, backups, etc.,
so in the examples I give, replace <filename>/build</filename> with the
location that you have chosen.</para>
<para>It's best to perform your update immediately after installing
<application>Koha</application> to ensure that you will be running the
very latest version. Also, if you setup the symlinks upon the initial
install you may find that it's easier to roll-back an update if
something should go wrong.</para>
</section>
</section>
<section>
<title>Checking Out Koha from Sourceforge</title>
<para>The checking out process is quite simple. Change your directory to
the directory you have selected as the root directory for your CVS
repository (mine is <filename>/build</filename>) and type: <userinput>cvs
-z3 -d:pserver:anonymous at cvs.sourceforge.net:/cvsroot/koha co
koha</userinput></para>
<para>At this point you should see a long listing of all the files that
are being checked out, and eventually it will finish and you will be back
at the command line:<literallayout>...
cvs checkout: Updating koha/z3950
U koha/z3950/processz3950queue
U koha/z3950/search.pl
U koha/z3950/z3950-daemon-launch.sh
U koha/z3950/z3950-daemon-shell.sh
U koha/z3950/z3950import.pl
cvs checkout: Updating koha/z3950/encodingfix
U koha/z3950/encodingfix/Biblio.pm
U koha/z3950/encodingfix/README-english
U koha/z3950/encodingfix/README-polish
U koha/z3950/encodingfix/search.pl
cvs checkout: Updating koha/z3950/server
U koha/z3950/server/zed-koha-server.pl
[root at frodo]#</literallayout></para>
<para>So now you have a new directory "koha" which contains the very
latest files and bugfixes for that version of
<application>Koha</application>. But this directory does not update your
installed version of <application>Koha</application>. To do that you will
need to link the installed directory tree to locations within the new
directory you just created. One confusing element of this step is the fact
that the CVS directory tree is quite different than the installation tree.
This is because the organization of the documents after an installation
doesn't make sense as the organization for developers to use while
programming.</para>
</section>
<section>
<title>Creating the Symlinks</title>
<para>The first step you'll want to take is to backup your existing
<application>Koha</application> directory tree. If you performed a default
install of <application>Koha</application> without customizing your
directory locations the following directories need to be backed up:</para>
<itemizedlist>
<listitem>
<para><filename>/usr/local/koha/intranet/cgi-bin</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/koha/intranet/htdocs/intranet-tmpl</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/koha/intranet/modules/C4</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/koha/opac/cgi-bin</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/koha/opac/htdocs</filename></para>
</listitem>
</itemizedlist>
<para>This is easily accomplished by using the <command>mv</command>
command. For example, to backup the
<filename>/usr/local/koha/intranet/cgi-bin</filename> directory, change
directories to <filename>/usr/local/koha/intranet</filename> and
issue:<literallayout>[root at frodo]# mv cgi-bin cgi-bin.bak</literallayout></para>
<para>If for some reason you are having trouble with the symlinking or you
want to revert back to the default directories you can always use this
backup to restore things (simply reverse the above command).</para>
<para>After backing up all of the above directories you'll be ready to
create the symlinks. This is accomplished using the <command>ln</command>
command with the <command>-s</command> option. For more info on
<command>ln</command>, see the <command>man</command> page.</para>
<para>Here are the symlink mappings we're going to create:</para>
<itemizedlist>
<listitem>
<para>[your cvs root dir]/koha --->
/usr/local/koha/intranet/cgi-bin</para>
</listitem>
<listitem>
<para>[your cvs root dir]/koha/koha-tmpl-intranet-tmpl --->
/usr/local/koha/intranet/htdocs/intranet-tmpl</para>
</listitem>
<listitem>
<para>[your cvs root dir]/koha/C4 --->
/usr/local/koha/intranet/modules</para>
</listitem>
<listitem>
<para>[your cvs root dir]/koha/opac --->
/usr/local/koha/opac/cgi-bin</para>
</listitem>
<listitem>
<para>[your cvs root dir]/koha/koha-tmpl/opac-tmpl --->
/usr/local/koha/opac/htdocs</para>
</listitem>
</itemizedlist>
<para>For example, to link the first directory listed above you would type
the following:<literallayout>[root at frodo]# ln -s /koha /usr/local/koha/intranet/cgi-bin</literallayout></para>
<section>
<title>Automating the Symlink Creation</title>
<para>Automating the symlink creation is a good idea if you want to have
a record of exactly what you did to create the symlinks. Automating also
makes it easier if you need to restore a <application>Koha</application>
installation quickly. Here's a simple Perl script that I use to create
my symlinks:</para>
<programlisting>#!/usr/bin/perl -w
# Configurable Variables
my $cvs_root_dir = ""; # insert your CVS repository root directory here
my $intranet_cgi = "/usr/local/koha/intranet/cgi-bin";
my $intranet_tmpl = "/usr/local/koha/intranet/htdocs/intranet-tmpl";
my $C4 = "/usr/local/koha/intranet/modules/C4";
my $opac_cgi = "/usr/local/koha/opac/cgi-bin";
my $opac_tmpl = "/usr/local/koha/opac/htdocs";
#backup the Koha directory tree items that will be symlinked:
sub backup_tree {
`mv $intranet_cgi $intranet_cgi.bak`;
`mv $intranet_tmpl $intranet_tmpl.bak`;
`mv $C4 $C4.bak`;
`mv $opac_cgi $opac_cgi.bak`;
`mv $opac_tmpl $opac_tmpl.bak`;
}
# create the symlinks to the CVS repository
sub create_symlinks {
`ln -s $cvs_root_dir $intranet_cgi`;
`ln -s $cvs_root_dir/koha-tmpl/intranet-tmpl $intranet_tmpl`;
`ln -s $cvs_root_dir/C4 $C4`;
`ln -s $cvs_root_dir/opac $opac_cgi`;
`ln -s $cvs_root_dir/koha-tmpl/opac-tmpl $opac_tmpl`;
}
backup_tree;
create_symlinks;</programlisting>
</section>
</section>
<section>
<title>Updating Your httpd.conf File</title>
<para>Depending on your settings you may need to add the following line to
both your intranet and opac virtual hosts configuration section of your
<filename>httpd.conf</filename> or
<filename>/etc/koha-httpd.conf</filename> file:<literallayout>Options +FollowSymLinks</literallayout></para>
<para>This ensures that <application>Apache</application> will allow
connections to symlinked directories.</para>
</section>
<section>
<title>Updating Your Database</title>
<para>The next step in updating your <application>Koha</application>
installation is to update your database. Over time, when bugs are fixed or
when new features are added, the <database>Koha</database> database is
subject to change. The <filename>updatedatbase</filename> script will
modify your database to the latest version. It's located in the
<filename>koha/updater</filename> directory of the CVS repository. It is
strongly recommended that you backup your database before running the
<filename>updatedatabase</filename> script. For more information on how to
backup your system see that section in the <application>Koha</application>
documentation.</para>
<para>In order to run this script you may need to export the environment
variable so that Perl knows where <filename>Context.pm</filename> is. You
can do this by running:<literallayout>[root at frodo]# export PERL5LIB="<emphasis>your_koha_cvsrepo</emphasis>"</literallayout>or
the path to your modules (usually
<filename>/usr/local/koha/intranet/modules</filename>). Alternatively you
can simply specify the path while executing the script:<literallayout>[root at frodo]# perl -I <emphasis>your_koha_cvsrepo</emphasis> updatedatabase</literallayout></para>
<para>You may see some messages that look like this:<literallayout>localhost:/build/koha/updater# perl -I /build/koha updatedatabase
connected to your DB. Checking & modifying it
Could convert to MyISAM database tables...
Alter z3950random in marc_breeding
Alter bookfundid in aqbookfund
Alter aqbudgetid in aqbudget
Alter id in z3950servers
Creating index on z3950results
Checking for data required in table userflags...
Checking for data required in table systempreferences... </literallayout></para>
</section>
</article>
--- NEW FILE ---
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<title>Backups and Restoring</title>
<articleinfo>
<pubdate>2004-12-15</pubdate>
<author>
<firstname>Joshua</firstname>
<surname>Ferraro</surname>
<email>jmf at kados dot org</email>
</author>
<revhistory>
<revision>
<revnumber>2.2.0</revnumber>
<date>2004-12-13</date>
<authorinitials>jmf</authorinitials>
<revdescription>
<para>Changes made by Joshua Ferraro. Original Document</para>
</revdescription>
</revision>
</revhistory>
</articleinfo>
<para>TO DO:</para>
<itemizedlist>
<listitem>
<para>Add more script examples for automation</para>
</listitem>
<listitem>
<para>Discuss replication in more detail</para>
</listitem>
</itemizedlist>
<section>
<title>Using this document</title>
<section>
<title id="copyright">Copyright and License</title>
<para>Copyright 2004 Joshua Ferraro <email>jmf at kados dot
org</email></para>
<para>This document is related to Koha and is licensed to you under the
GNU General Public License version 2 or later (<ulink
url="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</ulink>).
Koha-related documents may be reproduced and distributed in whole or in
part, in any medium physical or electronic, as long as this copyright
notice is retained on all copies.</para>
<para>You may create a derivative work and distribute it provided that
you: <orderedlist>
<listitem>
<para>License the derivative work with this same license, or the
Linux Documentation Project License (<ulink
url="http://www.tldp.org/COPYRIGHT.html">http://www.tldp.org/COPYRIGHT.html</ulink>).
Include a copyright notice and at least a pointer to the license
used.</para>
</listitem>
<listitem>
<para>Give due credit to previous authors and major
contributors.</para>
</listitem>
</orderedlist></para>
<para>Commercial redistribution is allowed and encouraged; however, the
author would like to be notified of any such distributions.</para>
</section>
<section>
<title id="disclaimer">Disclaimer</title>
<para>No liability for the contents of this document can be accepted.
Use the concepts, examples and information at your own risk. There may
be errors and inaccuracies, that could be damaging to your system.
Proceed with caution, and although this is highly unlikely, the
author(s) do not take any responsibility.</para>
<para>All copyrights are held by their by their respective owners,
unless specifically noted otherwise. Use of a term in this document
should not be regarded as affecting the validity of any trademark or
service mark. Naming of particular products or brands should not be seen
as endorsements.</para>
</section>
</section>
<section>
<title>Introduction</title>
<para>Understanding how to properly backup and restore your
<application>Koha</application> installation is a critical step in
administering <application>Koha</application> successfully. Not only are
these skills needed in an emergency, such as a hard drive failure on your
primary production machine, but they are also useful for when you update,
upgrade, or anytime you plan to custom modify either the filesystem or the
database.</para>
<para>There are three main components of <application>Koha</application>
that must be considered when backing up and restoring: the database, the
<application>Koha</application> filesystem, and the operating system
customizations for the system. This document describes every step
necessary for backing up and restoring both the database and the
filesystem and points out some important considerations when backing up
the operating system customizations -- these customizations often vary
widely from system to system.</para>
</section>
<section>
<title>Backing up and Restoring the Koha Database</title>
<section>
<title>Backups</title>
<para>There are many ways to backup <application>MySQL</application>
databases, or parts of databases. After reading this section I highly
recommend reading the <application>MySQL</application> manual sections
that discuss backing up and restoring data. You can find them online at
<ulink
url="http://dev.mysql.com/doc/mysql/en/index.html">http://dev.mysql.com/doc/mysql/en/index.html</ulink>.</para>
<para>Perhaps the best way to backup your <database>Koha</database>
database manually is the <command>mysqldump</command> application. To
backup the whole database you can invoke it thusly: <literallayout>[root at frodo]# mysqldump --add-drop-table -uroot -p<emphasis>your password</emphasis> Koha > 2004_11_30_koha.sql</literallayout></para>
<para>Notice that this naming convention uses the date, which makes it
easy to organize a number of backups in a directory without being
confused about which backup corresponds to which date. It's also clear
that it's an SQL backup. Choose your naming conventions wisely and
you'll thank yourself when you run into trouble.</para>
<para>Also notice the <userinput>--add-drop-table</userinput> option.
This specifies that when you restore the data you will not append the
data to existing data; additionally, if tables in your backup do not
exist in the database they will be created.</para>
<para>If you plan to work on a specific table and you'd like to back up
just that table you can use <command>mysqldump</command> to do that as
well. Suppose you're working on the <filename>issues</filename> table.
You can back it up thusly:<literallayout>[root at frodo]# mysqldump --add-drop-table -uroot -p<emphasis>your password</emphasis> Koha.issues > 2004_11_30_koha.issues.sql</literallayout></para>
<para>For more information on backups using the
<command>mysqldump</command> utility please see the
<application>MySQL</application> manual section <ulink
url="http://dev.mysql.com/doc/mysql/en/mysqldump.html">8.8: The
mysqldump Database Backup Program</ulink>. For more ways to backup your
database, the <application>MySQL</application> manual is your best
reference.</para>
<para>Now you can use the <command>gzip</command> program to compress
the sql file and reduce it's overall size for easier transport:
<literallayout>[root at frodo]# gzip 2004_11_30_koha.sql</literallayout></para>
</section>
<section>
<title>Restoration</title>
<para>To unzip your file (in case you need to restore your database) you
simply type:<literallayout>[root at frodo]# gzip -d filename.tgz</literallayout></para>
<para>An sql file can be used to restore data using the
<application>MySQL</application> command-line tool. Here's an example of
how to restore the <database>Koha</database> database using an sql file
called <filename>koha.sql</filename>:<literallayout>[root at frodo]# mysql -uroot -p<emphasis>your password</emphasis> Koha < koha.sql</literallayout></para>
<para>To restore a single table such as <filename>issues</filename> from
a file called <filename>koha.issues.sql</filename> you would
type:<literallayout>[root at frodo]# mysql -uroot -p<emphasis>your password</emphasis> Koha.issues < koha.issues.sql</literallayout></para>
</section>
<section>
<title>Role of Replication as Backup</title>
<para>In addition to being useful in load balancing, replication can
serve as a realtime backup for your <application>Koha</application>
system. You will need to manually promote a slave to serve as master,
and you will likely need to adjust your local configurations depending
on how you have your systems setup, but having replication in place will
probably ensure the fastest route to recovery from a complete system
crash. See the replication section of the
<application>MySQL</application> manual for more details.</para>
</section>
</section>
<section>
<title>Backing up the Koha Filesystem</title>
<para>Even if you don't plan to use the latest CVS updates for your
installation, it might be worth your time to centralize your
<application>Koha</application> installation filesystem to ease the backup
and restore process. For more info on how to achieve that see the
<citetitle>Updating Koha</citetitle> section of the
<application>Koha</application> documentation.</para>
<para>To backup the <application>Koha</application> installation directory
tree you need to ensure that all your <application>Koha</application>
files are being considered. Most of them are located by default in
<filename>/usr/local/koha</filename>. The
<filename>koha-httpd.conf</filename> and the
<filename>koha.conf</filename> files are located in the
<filename>/etc/</filename> directory.</para>
<section>
<title>Automating the Filesystem Backup</title>
<para>Here's a short Perl script that I run with <command>cron</command>
every evening. It backs up the filesystem using <command>tar</command>
and <command>gzip</command>. You'll need to change some of the
Configurable Variables for the script to work in your environment. Other
than that, it's pretty much ready to go -- setup <command>cron</command>
to run it nightly.<programlisting>#!/usr/bin/perl -w
#This script assumes that you have set up a CVS repository
#that is symlinked to your installation directories. For
#info on setting that up see the Koha manual "Updating Koha"
#Configurable Variables
my $koha_base = "/build/websites/openils.com/koha"; #location of Koha cvs repo
my $bak_loc = "/build/backups"; #where to put backups
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst)
= localtime(time);
$year += "1900";
my $date = "$year-$mon-$mday";
#Backup the filesystem
print "Backing up the filesystem\n";
print "Please wait ...";
`rm -rf $koha_base.bak`; #remove the previous backup
`cp $koha_base $koha_base.bak`; #make a new backup
`tar -cvzf $bak_loc/$date-kohafilesystem.tgz $koha_base.bak`; #targzip it</programlisting></para>
</section>
</section>
<section>
<title>Backing up the Local Operating System Configuration</title>
<para>It's best to write a script to perform all the local operating
system configurations as you would manually perform them to ensure that in
the event of an emergency, you can simply run the script to set everything
the way you had it before.</para>
<para>The list of possible custom configuration files for your system is
unlimited, so I can just list a few common examples that you might want to
consider including as part of your regular backup scheme:</para>
<itemizedlist>
<listitem>
<para><filename>httpd.conf</filename></para>
</listitem>
<listitem>
<para><filename>my.cnf</filename></para>
</listitem>
<listitem>
<para>any custom <command>cron</command> jobs related to
<application>Koha</application></para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Storing your Backup Offsite Using scp</title>
<para>You may want to keep a copy of your database, filesystem and
operating system customizations on your production server to ease the
process of restoring should the need arise. However, what if your hard
drive on that machine crashes? It's a very good idea to store your backups
on a different machine (or two or three) and it's probably a good ideal to
store them in a different building too.</para>
<para>Perhaps the best way to avoid the problems inherent in physical
backup medium such as a tape (that you may never really be sure is going
to work anyway) is to use <command>ssh</command> and in particular
<command>scp</command> as a part of your backup process. Why mess with
tapes when you can securely copy a file from one system to another? You
can invoke <command>scp</command> thusly:<literallayout>[root at frodo]# scp koha.bak jmf at sam.openils.com:/build/backups/</literallayout></para>
<para>The <userinput>:</userinput> signifies that this is a network
address and also allows a specific directory to be specified on the
receiving machine -- in this case,
<systemitem>sam.openils.com</systemitem> has a
<filename>/build/backups</filename> directory where I store
backups.</para>
</section>
</article>
More information about the Koha-cvs
mailing list