doc: Debian/Ubuntu installation docs

diff --git a/doc/install-packages.sgml b/doc/install-packages.sgml
index d48cae5d23f19e580af0d9b53a1f89f4285c8b14..b0dea24b69abcc113df0a2b04d63f0e8aa874980 100644 (file)
--- a/doc/install-packages.sgml
+++ b/doc/install-packages.sgml
@@ -186,16 +186,147 @@
  </sect2>
 
  <sect2 id="installation-packages-debian" xreflabel="Installing from packages on Debian or Ubuntu">
-  <title>Installing from packages on Debian or Ubuntu</title>
+  <title>Debian or Ubuntu</title>
 
   <para>
-   At time of writing packages for Debian and Ubuntu are available from
+   Packages for Debian and Ubuntu are available from
    <ulink url="http://packages.2ndquadrant.com/bdr/apt/">http://packages.2ndquadrant.com/bdr/apt/</ulink>.
-   Debian and Ubuntu packaging is still subject to ongoing development
-   and may change. See <ulink url="http://bdr-project.org">bdr-project.org</ulink>
-   for the latest information.
   </para>
 
+  <sect3>
+   <title>Adding the BDR repository</title>
+
+   <para>
+    To install &bdr; or &udr; from DEBs you first need to add the BDR
+    repository to your sever.
+   </para>
+
+   <note>
+    <para>
+     The packages are signed with 2ndQuadrant's master packaging/releases
+     signing key. See <xref linkend="appendix-signatures">.
+    </para>
+   </note>
+
+   <para>
+    Create <filename>/etc/apt/sources.list.d/2ndquadrant.list</> with following
+    contents. Note that the distributions are called
+    <literal>codename-2ndquadrant</>. In the example, replace
+    <literal>wheezy</> with the actual distribution you are using:
+    <programlisting>
+     deb http://apt.postgresql.org/pub/repos/apt/ wheezy-pgdg main
+    </programlisting>
+    (You may determine the codename of your distribution by running lsb_release
+    -c).
+   </para>
+
+   <para>
+    Import the repository key from http://packages.2ndquadrant.com/bdr/apt/AA7A6805.asc,
+    update the package lists, and start installing packages:
+    <programlisting>
+     wget --quiet -O - http://packages.2ndquadrant.com/bdr/apt/AA7A6805.asc | sudo apt-key add -
+     sudo apt-get update
+     sudo apt-get install postgresql-9.4-udr-plugin
+    </programlisting>
+   </para>
+
+  </sect3>
+
+  <sect3>
+   <title>Installing PostgreSQL &pgmajorversion; and &bdr; from packages for Debian or Ubuntu</title>
+
+   <sect4>
+    <title>Remove the <literal>postgresql-9.4</literal> packages, if installed</title>
+
+    <note>
+     <para>If you don't already have PostgreSQL &pgmajorversion; installed, simply skip this step.</para>
+    </note>
+
+    <para>
+     &bdr; requires a patched version of PostgreSQL &pgmajorversion;
+     that conflicts with the official packages. If you already have PostgreSQL
+     &pgmajorversion; installed either from apt.postgresql.org or your official
+     distribution repository, you will need to make a dump of all your
+     databases, then uninstall the official PostgreSQL &pgmajorversion;
+     packages before you can install &bdr;.
+    </para>
+
+    <para>
+     The BDR Debian packages cannot co-exist with stock PostgreSQL
+     &pgmajorversion;. <emphasis>However BDR uses the same data directory as
+     stock &pgmajorversion;, to ensure the compatibility with system utilities,
+     so you should always first backup the existing instalation before trying
+     to install the BDR PostgreSQL packages</emphasis>.
+    </para>
+
+    <para>
+     Once you have fully backed up all your databases:
+     <programlisting>
+      sudo apt-get remove postgresql-9.4
+     </programlisting>
+     Check the list of packages to be removed carefully,
+     approve the removal if appropriate, and proceed with the removal.
+    </para>
+
+   </sect4>
+
+   <sect4>
+    <title>Install the &bdr; packages</title>
+
+    <para>
+     To differentiate between the &bdr; specific packages and vanilla
+     <productname>PostgreSQL</> packages all the package names start with
+     <literal>postgresql-bdr</> instead of plain <literal>postgresql</>.
+     So if you want to install the PostgreSQL package with BDR patches
+     you should run:
+     <programlisting>
+      sudo apt-get update
+      sudo apt-get install postgresql-bdr-9.4
+     </programlisting>
+    </para>
+
+    <note>
+     <para>
+      If you attempt to to install this package when you already have
+      postgresql-9.4 installed you will get informed that the official package
+      will be removed and confirmation will be required. <emphasis>Do not
+      remove the old packages if you have existing data directory!</>
+     </para>
+    </note>
+
+    <para>
+     Once &bdr; is installed you will need to initdb a new database,
+     make any required changes to <filename>postgresql.conf</filename>
+     and <filename>pg_hba.conf</filename>, etc, as per any new
+     PostgreSQl install. This works with standard system utilities like
+     <command>pg_createcluster</>.
+    </para>
+
+    <para>
+     You can then proceed with BDR-specific configuration per
+     <xref linkend="settings"> and <xref linkend="quickstart">.
+    </para>
+
+   </sect4>
+
+  </sect3>
+
+  <sect3>
+   <title>Installing &udr; from packages for Debian or Ubuntu</title>
+
+   <para>
+    To install &udr; install PostgreSQL &pgmajorversion; from <ulink
+    url="http://apt.postgresql.org/">apt.postgresql.org</ulink> as
+    normal. Then add the BDR repository as outlined above.
+    Finally, install the UDR package:
+    <programlisting>
+     sudo apt-get update
+     sudo apt-get install postgresql-9.4-udr-plugin
+    </programlisting>
+   </para>
+
+  </sect3>
+
  </sect2>
 
  <sect2 id="installation-packages-windows" xreflabel="Installing from packages on Windows">