<!--  -->
<sect1 id="installation">
<title>&slony1; Building & Installation</title>

<indexterm><primary>installation instructions</primary></indexterm>

<note> <para>For &windows; users: Unless you are planning on hacking
the &slony1; code, it is highly recommended that you download and
install a prebuilt binary distribution and jump straight to the
configuration section below.  Prebuilt binaries are available 
from the StackBuilder application included in the <ulink url="http://www.enterprisedb.com/downloads/postgres-postgresql-downloads"> EnterpriseDB
PostgreSQL installer</ulink>

<para> There are also RPM binaries available in the <ulink url="http://yum.postgresql.org"> PostgreSQL YUM repository</ulink> site for recent
versions of &slony1; for recent versions of &postgres;.
</para>
</note>

<para> This section discusses building &slony1; from source.</para>

<para>You should have obtained the &slony1; source from the previous
step. Unpack it.</para>

<screen>
gunzip slony.tar.gz;
tar xf slony.tar
</screen>

<para> This will create a directory under the current directory with
the &slony1; sources.  Head into that that directory for the rest of
the installation procedure.</para>

<sect2>
<title>Short Version</title>

<indexterm><primary> installation: short version </primary></indexterm>

<para>
<screen>
PGMAIN=/usr/local/pgsql839-freebsd-2008-09-03 \
./configure \
    --with-pgconfigdir=$PGMAIN/bin
gmake all; gmake install
</screen>
</para>
</sect2>

<sect2>
<title>Configuration</title>

<indexterm><primary>configuration instructions</primary></indexterm>

<para> &slony1; normally needs to be built and installed by the
&postgres; Unix user.  The installation target must be identical to
the existing &postgres; installation particularly in view of the fact
that several &slony1; components represent libraries and SQL scripts
that need to be in the &slony1; <filename>lib</filename> and
<filename>share</filename> directories. </para>

<para>The first step of the installation procedure is to configure the
source tree for your system.  This is done by running the
<application>configure</application> script.&slony1; is configured by 
pointing it to the
various &postgres; library, binary, and include directories.  For a
full list of these options, use the command <command>./configure
--help</command>. </para>

<para> It is sufficient, for the purposes of building a usable build,
to run <command>configure
<option>--with-pgconfigdir=/some/path/somewhere</option></command>,
where <filename>/some/path/somewhere</filename> is the directory where
the &postgres; program <application>pg_config</application> is
located.  Based on the output of <application>pg_config</application>,
the <filename>configure</filename> script determines the various
locations where &postgres; components are found, which indicate where
the essential components of &slony1; must be installed.</para>

<para> For a full listing of configuration options, run the command
<command>./configure --help</command>.</para>

<warning> <para> Beware: <application>configure</application> defaults
to permit indicating values for various paths, including
<quote>generic</quote> values:
<itemizedlist>
<listitem><para> <option>--bindir</option>=DIR </para> <para>           user executables [EPREFIX/bin] </para></listitem>
<listitem><para> <option>--sbindir</option>=DIR </para> <para>          system admin executables [EPREFIX/sbin] </para></listitem>
<listitem><para> <option>--libexecdir</option>=DIR </para> <para>       program executables [EPREFIX/libexec] </para></listitem>
<listitem><para> <option>--sysconfdir</option>=DIR </para> <para>       read-only single-machine data [PREFIX/etc] </para></listitem>
<listitem><para> <option>--sharedstatedir</option>=DIR </para> <para>   modifiable architecture-independent data [PREFIX/com] </para></listitem>
<listitem><para> <option>--localstatedir</option>=DIR </para> <para>    modifiable single-machine data [PREFIX/var] </para></listitem>
<listitem><para> <option>--libdir</option>=DIR </para> <para>           object code libraries [EPREFIX/lib] </para></listitem>
<listitem><para> <option>--includedir</option>=DIR </para> <para>       C header files [PREFIX/include] </para></listitem>
<listitem><para> <option>--oldincludedir</option>=DIR </para> <para>    C header files for non-gcc [/usr/include] </para></listitem>
<listitem><para> <option>--datarootdir</option>=DIR </para> <para>      read-only arch.-independent data root [PREFIX/share] </para></listitem>
<listitem><para> <option>--datadir</option>=DIR </para> <para>          read-only architecture-independent data [DATAROOTDIR] </para></listitem>
<listitem><para> <option>--infodir</option>=DIR </para> <para>          info documentation [DATAROOTDIR/info] </para></listitem>
<listitem><para> <option>--localedir</option>=DIR </para> <para>        locale-dependent data [DATAROOTDIR/locale] </para></listitem>
<listitem><para> <option>--mandir</option>=DIR </para> <para>           man documentation [DATAROOTDIR/man] </para></listitem>
<listitem><para> <option>--docdir</option>=DIR </para> <para>           documentation root [DATAROOTDIR/doc/slony1] </para></listitem>
<listitem><para> <option>--htmldir</option>=DIR </para> <para>          html documentation [DOCDIR] </para></listitem>
<listitem><para> <option>--dvidir</option>=DIR </para> <para>           dvi documentation [DOCDIR] </para></listitem>
<listitem><para> <option>--pdfdir</option>=DIR </para> <para>           pdf documentation [DOCDIR] </para></listitem>
<listitem><para> <option>--psdir</option>=DIR </para> <para>            ps documentation [DOCDIR] </para></listitem>
</itemizedlist></para>

<para> There are also &postgres;-specific options specified, which <emphasis>should not be expressly set</emphasis>, as <application>pg_config</application> should already provide correct values:

<itemizedlist>
<listitem><para> <option>--with-pgbindir</option>=DIR</para> <para>           Location of the PostgreSQL postmaster. </para></listitem>
<listitem><para> <option>--with-pgincludedir</option>=DIR</para> <para>       Location of the PostgreSQL headers. </para></listitem>
<listitem><para> <option>--with-pgincludeserverdir</option>=DIR</para> <para> Location of the PostgreSQL server headers. </para></listitem>
<listitem><para> <option>--with-pglibdir</option>=DIR</para> <para>           Location of the PostgreSQL libs. </para></listitem>
<listitem><para> <option>--with-pgpkglibdir</option>=DIR</para> <para>        Location of the PostgreSQL pkglibs. E.g. plpgsql.so </para></listitem>
<listitem><para> <option>--with-pgsharedir</option>=DIR</para> <para>         Location of the PostgreSQL share dir. E.g. postgresql.conf.sample </para></listitem>
</itemizedlist></para>

</warning>

<para>The compile of &postgres; must be expressly
configured with the option <command>--enable-thread-safety</command>
to provide correct client libraries. </para>

<para> &slony1; requires that the &postgres; server headers be installed. 
Some binary distributions of &postgres; include this is a a -dev package.</para>

<para>After running configure, you may wish to review the file
<filename>Makefile.global</filename> to ensure it is looking in the
right places for all of the components. </para>


</sect2>

<sect2>
<title>Example</title>

<para> After determining that the &postgres; instance to be used is
installed in
<filename>/opt/dbs/pgsql746-aix-2005-04-01</filename>:</para>

<screen>
PGMAIN=/opt/dbs/pgsql746-aix-2005-04-01 \
./configure \
    --with-pgconfigdir=$PGMAIN/bin 
</screen>

<para>The <application>configure</application> script will run a
number of tests to guess values for various dependent variables and
try to detect some quirks of your system. </para>

</sect2>

<sect2>
<title>Build</title>

<para>To start the build process, type

<screen>
gmake all
</screen></para>

<para> Be sure to use GNU make; on BSD systems, it is called
<application>gmake</application>; on Linux, GNU make is typically the
<quote>native</quote> <application>make</application>, so the name of
the command you type in may be either <command>make</command> or
<command>gmake</command>.  On other platforms, you may need additional
packages or even install GNU make from scratch.  The build may take
anywhere from a few seconds to 2 minutes depending on how fast your
hardware is at compiling things.  The last line displayed should
be</para>

<para> <command> All of Slony-I is successfully made.  Ready to
install.  </command></para>
</sect2>

<sect2>
<title> Installing &slony1 Once Built;</title>

<para> To install &slony1;, enter

<command>
gmake install
</command></para>

<para>This will install files into the postgresql install directory as
specified by the <command>configure</command>
<option>--prefix</option> option used in the &postgres; installation.
Make sure you have appropriate permissions to write into that area.
Commonly you need to do this either as root or as the postgres user.
</para>

<para>The main list of files installed within the &postgres; instance
is, for versions of &slony1; </para>

<itemizedlist>
<listitem><para><filename> $bindir/slon</filename></para></listitem>
<listitem><para><filename> $bindir/slonik</filename></para></listitem>
<listitem><para><filename> $libdir/slony1_funcs.$(SLONY_VERSION).$(DLSUFFIX)</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_base.$(SLONY_VERSION).sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.$(SLONY_VERSION).sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.v83.$(SLONY_VERSION).sql</filename></para></listitem>
<listitem><para><filename> $datadir/slony1_funcs.v84.$(SLONY_VERSION).sql</filename></para></listitem>
</itemizedlist>

</sect2>

<sect2 id="buildingwin32"><title>Building on Win32</title>
<para>
Building &slony1; on Win32 with the Microsoft SDK (Visual Studio) is 
different than building &slony1; on other platforms.  Visual Studio
builds can be done with out involving configure or gmake.

To build &slony1 you need
</para>
<itemizedlist>
<listitem><para>The &slony1; source from a source distribution tar
(The distribution tar files contain pre-built copies of the parser and 
scanner generated files.  The Win32 makefiles do not currently support
building these).</para></listitem>
<listitem><para>&postgres; binaries, headers and libraries. </para></listitem>
<listitem><para> <ulink url="http://sources.redhat.com/pthreads-win32">pthreads for win32</ulink></para></listitem>
<listitem><para>The Microsoft SDK 6.1 or Visual Studio 2008 (other versions
might work)</para></listitem>
<listitem><para><ulink url="http://sourceforge.net/projects/gettext/">gettext 
for win32</ulink> or <ulink url="http://ftp.acc.umu.se/pub/GNOME/binaries/win64/dependencies/">gettext for win64</para></listitem>
</itemizedlist>

<para>
To compile the &slony1; binaries you will need to
<itemizedlist>
<listitem><para>Set the environment variables PGSHARE,PG_INC,PG_LIB,
PTHREADS_INC,PTHREADS_LIB, GETTEXT_LIB to point to the proper locations
based on where these applications were installed.  You will also
need to set SLONY_VERSION to the version of slony you are building.  
The PGVER environment variable should be set the PostgreSQL MAJOR
number of the PostgreSQL instance you are compiling against(8.4 , 9.1, etc..). 
For example</para>
<programlisting>
set PG_INC=c:\Postgresql\9.0\include
set PG_LIB=c:\Postgresql\9.0\lib
set PGSHARE=c:\\Postgresql\\9.0\\share
set PTHREADS_INC=c:\pthreads-win32\include
set PTHREADS_LIB=c:\pthreads-win32\lib
set GETTEXT_LIB=c:\gettext\lib
set GETTEXT_INC=c:\gettext\include
set SLONY_VERSION=2.2.0
set PGVER=9.2
</programlisting>
<para>
Note that the backslash characters must be escaped for PGSHARE as in the
above example</para>
</listitem>

<para>
From the Visual Studio or Microsoft Windows SDK command prompt run
<programlisting>
cd src\backend
nmake /f win32.mak slony1_funcs.%SLONY_VERSION%.dll
cd ..\slon
nmake /f win32.mak slon.exe
cd ..\slonik
nmake /f win32.mak slonik.exe
</programlisting>
</para>
<para>
src\backend\slony1_funcs.$SLONY_VERSION.dll and any of the .sql files in 
src\backend need to be installed in your postgresql $share directory.
The SQL files also need to be renamed to contain the slony version number in 
them. For example the slony1_funcs.sql should be renamed slony1_funcs.2.2.1.sql

<programlisting>
copy slony1_base.sql c:\Program Files\Postgresql\9.1\share\slony1_base.2.2.0.sql
copy slony1_base.v83.sql c:\Program Files\Postgresql\9.1\share\slony1_base.v83.2.2.0.sql
copy slony1_base.v84.sql c:\Program Files\Postgresql\9.1\share\slony1_base.v84.2.2.0.sql
copy slony1_funcs.sql c:\Program Files\Postgresql\9.1\share\slony1_funcs.2.2.0.sql
copy slony1_funcs.v83.sql c:\Program Files\Postgresql\9.1\share\slony1_funcs.v83.2.2.0.sql
copy slony1_funcs.v84.sql c:\Program Files\Postgresql\9.1\share\slony1_funcs.v84.2.2.0.sql
</programlisting>



</para>

<para>
pthreadVC.dll from the pthreads-win32 package also needs to be copied to the
directory you install the slon.exe and slonik.exe binaries in
</para>

</sect2>

<sect2 id="buildingdocs"> <title> Building Documentation: Admin Guide </title>

<indexterm><primary> building &slony1; documentation </primary></indexterm>

<para> The document you are reading now is a fairly extensive
<quote>Administrator's Guide</quote> containing what wisdom has been
discovered and written down about the care and feeding of &slony1;.</para>

<para> This is only built if you specify <command>--with-docs</command></para>

<para> Note that you may have difficulty building the documentation on
older Red Hat systems (RHEL4 and below) See <ulink url=
"https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=159382"> Bug
159382 (For RHEL) </ulink> See the <filename>INSTALL</filename> file
for a workaround for Fedora...</para>

<para>A pre-built copy of the <quote>admin guide</quote> should be
readily available, either in the form of a separate tarball nearby, or
in the directory <filename>doc/adminguide/prebuilt</filename> </para>

</sect2>

<sect2>
<title> Installing &slony1; from RPMs</title>
<indexterm><primary>RPMs for &slony1;</primary> </indexterm>

<para> Even though &slony1; can be compiled and run on most Linux
distributions, it is also possible to install &slony1; using binary
packages. Slony Global Development Team provides official RPMs and
SRPMs for many versions or Red Hat and Fedora .</para>

<para>The RPMs are available at <ulink
url="http://yum.postgresql.org"> &postgres RPM Repository
</ulink>. Please read the howto provided in the website for configuring
yum to use that repository. Please note that the RPMs will look for RPM
installation of &postgres;, so if you install &postgres; from source,
you should manually ignore the RPM dependencies related to
&postgres;.</para>

<para>Installing &slony1; using these RPMs is as easy as
installing any RPM.</para>

<screen>yum install slony1</screen>

<para>yum will pick up dependencies. This repository provides Slony-I binaries
built against every supported &postgres version.</para>

<para>The RPM installs the files into their usual places. The
configuration files are installed under <filename>/etc</filename>, the
binary files are installed in <filename>/usr/bin</filename>, libraries
are installed in <filename>/usr/lib/pgsql</filename>, and finally the
docs are installed in
<filename>/usr/share/doc/slony1</filename>.</para>

</sect2>

<sect2>
<title> Installing the &slony1; service on &windows;</title>

<indexterm><primary>installing &slony1; on &windows;</primary></indexterm>

<para> On &windows; systems, instead of running one <xref
linkend="slon"> daemon per node, a single slon service is installed
which can then be controlled through the <command>Services</command>
control panel applet, or from a command prompt using the
<command>net</command> command.</para>

<screen>
C:\Program Files\PostgreSQL\8.3\bin> slon -regservice my_slon
Service registered.
Before you can run Slony, you must also register an engine!

WARNING! Service is registered to run as Local System. You are
encouraged to change this to a low privilege account to increase
system security. 
</screen>

<para> Once the service is installed, individual nodes can be setup
by registering slon configuration files with the service.</para>

<screen>
C:\Program Files\PostgreSQL\8.3\bin> slon -addengine my_slon c:\node1.conf
Engine added.
</screen>

<para>Other, self explanatory commands include <command>slon -unregservice 
&lt;service name&gt;</command>, <command>slon -listengines 
&lt;service name&gt;</command> and <command>slon -delengine 
&lt;service name&gt; &lt;config file&gt;</command>.</para> 

<para> For further information about the &windows; port, you may want
to see the following URLs: </para>

<itemizedlist>

<listitem><para> <ulink
url="http://developer.pgadmin.org/~hiroshi/Slony-I/"> Slony-I Windows
installer sample </ulink> </para> </listitem>

</itemizedlist>

</sect2>

</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:"slony.sgml"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
