<!--  -->
<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>Visual Studio(2017 has been tested against the current version of Slony and PostgreSQL 10 x64).
The Microsoft SDK 6.1 or Visual Studio 2008 had been tested against earlier versions
(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 or pthreadVC2.dll from the pthreads-win32 package also needs to be copied to the
directory you install the slon.exe and slonik.exe binaries in.

The Visual C++ redistributable might also be required.

</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:
-->
