Add Markdown extension to relevant root-directory files

1 files changed, 322 insertions, 0 deletions

diff --git a/INSTALL.Unix.md b/INSTALL.Unix.md
new file mode 100644
index 000000000..8b4b53d38
--- /dev/null
+++ b/INSTALL.Unix.md
@@ -0,0 +1,322 @@
+Apache CouchDB INSTALL.Unix
+==========================
+
+A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
+
+Community installation guides are available on the wiki:
+
+    http://wiki.apache.org/couchdb/Installation
+
+If you are trying to build CouchDB from a git checkout rather than
+a .tar.gz, see the `DEVELOPERS` file.
+
+This document is the canonical source of installation
+information. However, many systems have gotchas that you need to be
+aware of. In addition, dependencies frequently change as distributions
+update their archives. If you're running into trouble, be sure to
+check out the wiki. If you have any tips to share, please also update
+the wiki so that others can benefit from your experience.
+
+Troubleshooting
+---------------
+
+There is a troubleshooting guide:
+
+    http://wiki.apache.org/couchdb/Troubleshooting
+
+There is a wiki for general documentation:
+
+    http://wiki.apache.org/couchdb/
+
+There are collection of friendly mailing lists:
+
+    http://couchdb.apache.org/community/lists.html
+
+Please work through these in order if you experience any problems.
+
+Dependencies
+------------
+
+You should have the following installed:
+
+ * Erlang OTP (>=R14B01, =<R17) (http://erlang.org/)
+ * ICU                          (http://icu-project.org/)
+ * OpenSSL                      (http://www.openssl.org/)
+ * Mozilla SpiderMonkey (1.8.5) (http://www.mozilla.org/js/spidermonkey/)
+ * GNU Make                     (http://www.gnu.org/software/make/)
+ * GNU Compiler Collection      (http://gcc.gnu.org/)
+ * libcurl                      (http://curl.haxx.se/libcurl/)
+ * help2man                     (http://www.gnu.org/s/help2man/)
+ * Python (>=2.7) for docs      (http://python.org/)
+ * Python Sphinx (>=1.1.3)      (http://pypi.python.org/pypi/Sphinx)
+
+It is recommended that you install Erlang OTP R13B-4 or above where
+possible.  You will only need libcurl if you plan to run the
+JavaScript test suite. And help2man is only need if you plan on
+installing the CouchDB man pages.  Python and Sphinx are only required
+for building the online documentation.
+
+Debian-based Systems
+~~~~~~~~~~~~~~~~~~~~
+
+You can install the dependencies by running:
+
+    sudo apt-get install build-essential erlang-base-hipe \
+        erlang-dev erlang-manpages erlang-eunit erlang-nox \
+        libicu-dev libmozjs185-dev libcurl4-openssl-dev \
+        pkg-config rebar
+
+There are lots of Erlang packages. If there is a problem with your
+install, try a different mix. There is more information on the
+wiki. Additionally, you might want to install some of the optional
+Erlang tools which may also be useful.
+
+Be sure to update the version numbers to match your system's available
+packages.
+
+For up to date instructions, please see:
+
+  http://wiki.apache.org/couchdb/Installing_on_Debian
+
+  http://wiki.apache.org/couchdb/Installing_on_Ubuntu
+
+Unfortunately, it seems that installing dependencies on Ubuntu is
+troublesome.
+
+RedHat-based (Fedora, Centos, RHEL) Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can install the dependencies by running:
+
+    sudo yum install autoconf autoconf-archive automake \
+        curl-devel erlang-asn1 erlang-erts erlang-eunit \
+        erlang-os_mon erlang-xmerl erlang-rebar help2man \
+        js-devel libicu-devel libtool perl-Test-Harness
+
+While CouchDB builds against the default js-devel-1.7.0 included in
+some distributions, it's recommended to use a more recent
+js-devel-1.8.5.
+
+Mac OS X
+~~~~~~~~
+
+To build CouchDB from source on Mac OS X, you will need to install
+the Command Line Tools:
+
+    xcode-select --install
+
+You can then install the other dependencies by running:
+
+    brew install autoconf autoconf-archive automake libtool \
+        erlang icu4c spidermonkey curl pkg-config rebar
+
+You will need Homebrew installed to use the `brew` command.
+
+Learn more about Homebrew at:
+
+    http://mxcl.github.com/homebrew/
+
+Some versions of Mac OS X ship a problematic OpenSSL library. If
+you're experiencing troubles with CouchDB crashing intermittently with
+a segmentation fault or a bus error, you will need to install your own
+version of OpenSSL. See the troubleshooting guide, mentioned above,
+for more information.
+
+FreeBSD
+-------
+
+FreeBSD requires the use of GNU Make. Where `make` is specified in this
+documentation, substitute `gmake`.
+
+You can install this by running:
+
+    pkg install gmake
+
+Installing
+----------
+
+Once you have satisfied the dependencies you should run:
+
+    ./configure
+
+This script will configure CouchDB to be installed into `/usr/local`
+by default.
+
+If you wish to customize the installation, pass `--help` to this
+script.
+
+If everything was successful you should see the following message:
+
+    You have configured Apache CouchDB, time to relax.
+
+Relax.
+
+To install CouchDB you should run:
+
+    make && sudo make install
+
+You only need to use `sudo` if you're installing into a system directory.
+
+Try `gmake` if `make` is giving you any problems.
+
+If everything was successful you should see the following message:
+
+    You have installed Apache CouchDB, time to relax.
+
+Relax.
+
+User Registration
+-----------------
+
+You should create a special `couchdb` user for CouchDB.
+
+On many Unix-like systems you can run:
+
+    adduser --system \
+            --home /usr/local/var/lib/couchdb \
+            --no-create-home \
+            --shell /bin/bash \
+            --group --gecos \
+            "CouchDB Administrator" couchdb
+
+On Mac OS X you can use the Workgroup Manager to create users:
+
+  http://www.apple.com/support/downloads/serveradmintools1047.html
+
+You must make sure that:
+
+    * The user has a working POSIX shell
+
+    * The user's home directory is `/usr/local/var/lib/couchdb`
+
+You can test this by:
+
+    * Trying to log in as the `couchdb` user
+
+    * Running `pwd` and checking the present working directory
+
+Change the ownership of the CouchDB directories by running:
+
+    chown -R couchdb:couchdb /usr/local/etc/couchdb
+    chown -R couchdb:couchdb /usr/local/var/lib/couchdb
+    chown -R couchdb:couchdb /usr/local/var/log/couchdb
+    chown -R couchdb:couchdb /usr/local/var/run/couchdb
+
+Change the permission of the CouchDB directories by running:
+
+    chmod 0770 /usr/local/etc/couchdb
+    chmod 0770 /usr/local/var/lib/couchdb
+    chmod 0770 /usr/local/var/log/couchdb
+    chmod 0770 /usr/local/var/run/couchdb
+
+Update the permissions for your `default.ini` file:
+
+    chmod 0644 /usr/local/etc/couchdb/default.ini
+
+First Run
+---------
+
+You can start the CouchDB server by running:
+
+    sudo -i -u couchdb couchdb
+
+This uses the `sudo` command to run the `couchdb` command as the
+`couchdb` user.
+
+When CouchDB starts it should eventually display the following
+message:
+
+    Apache CouchDB has started, time to relax.
+
+Relax.
+
+To check that everything has worked, point your web browser to:
+
+    http://127.0.0.1:5984/_utils/index.html
+
+From here you should run the test suite in Firefox.
+
+Running as a Daemon
+-------------------
+
+SysV/BSD-style Systems
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the `couchdb` init script to control the CouchDB daemon.
+
+On SysV-style systems, the init script will be installed into:
+
+    /usr/local/etc/init.d
+
+On BSD-style systems, the init script will be installed into:
+
+    /usr/local/etc/rc.d
+
+We use the `[init.d|rc.d]` notation to refer to both of these
+directories.
+
+You can control the CouchDB daemon by running:
+
+    /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|status]
+
+If you wish to configure how the init script works, you can edit:
+
+    /usr/local/etc/default/couchdb
+
+Comment out the `COUCHDB_USER` setting if you're running as a
+non-superuser.
+
+To start the daemon on boot, copy the init script to:
+
+    /etc/[init.d|rc.d]
+
+You should then configure your system to run the init script
+automatically.
+
+You may be able to run:
+
+    sudo update-rc.d couchdb defaults
+
+If this fails, consult your system documentation for more information.
+
+A `logrotate` configuration is installed into:
+
+    /usr/local/etc/logrotate.d/couchdb
+
+Consult your `logrotate` documentation for more information.
+
+It is critical that the CouchDB logs are rotated so as not to fill
+your disk.
+
+Mac OS X
+~~~~~~~~
+
+You can use the `launchctl` command to control the CouchDB daemon.
+
+You can load the configuration by running:
+
+    sudo launchctl load \
+         /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
+
+You can stop the CouchDB daemon by running:
+
+    sudo launchctl unload \
+         /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
+
+You can start CouchDB by running:
+
+    sudo launchctl start org.apache.couchdb
+
+You can restart CouchDB by running:
+
+    sudo launchctl stop org.apache.couchdb
+
+You can edit the launchd configuration by running:
+
+    open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
+
+To start the daemon on boot, copy the configuration file to:
+
+    /Library/LaunchDaemons
+
+Consult your system documentation for more information.