rewrote and improved core documentation for clarity, utility and compatibility with Markdown

git-svn-id: https://svn.apache.org/repos/asf/incubator/couchdb/trunk@642660 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 52 insertions, 0 deletions

diff --git a/TROUBLESHOOTING b/TROUBLESHOOTING
new file mode 100644
index 00000000..e7582b12
--- /dev/null
+++ b/TROUBLESHOOTING
@@ -0,0 +1,52 @@
+# Troubleshooting #
+
+## Upgrade ##
+
+Have you built CouchDB from the Subversion repository?
+
+Did you do a svn up that seemed to break everything?
+
+After every update you must run the following command:
+
+    ./bootstrap -C
+
+If you still have problems building try the next troubleshooting tip.
+
+## First Run ##
+
+Having problems getting CouchDB to run for the first time?
+
+Follow this simple procedure and report back to mailing list (or IRC) with the
+output of each step.
+
+  1. Note down the name of your operating system and your processor
+     architecture.
+
+  2. Note down the installed versions of CouchDB's dependancies.
+
+  3. Checkout a fresh version from Subversion:
+
+         svn checkout http://couchdb.googlecode.com/svn/trunk/ couchdb
+
+  4. Bootstrap from the couchdb directory:
+
+         ./bootstrap -C
+
+  5. Build into a temporary directory:
+
+         ./configure --prefix=/tmp/couchdb && make && make install
+
+  6. Run the couchdb command and log the output:
+
+         /tmp/couchdb/bin/couchdb
+
+  7. Use your system's kernel trace tool and log the output of the above
+     command.
+
+    1. Linux systems should use strace:
+
+            strace /tmp/couchdb/bin/couchdb 2> strace.out
+
+    2. Please add documentation for your system...
+
+  8. Report back to the mailing list (or IRC) with the output from each step.