You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/10/22 18:20:43 UTC
git commit: updated refs/heads/1912-troubleshooting-guide to bdf38a9
Updated Branches:
refs/heads/1912-troubleshooting-guide [created] bdf38a982
Initial commit for troubleshooting guide.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/bdf38a98
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/bdf38a98
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/bdf38a98
Branch: refs/heads/1912-troubleshooting-guide
Commit: bdf38a9821d808fd330f87a84e1e73801e3dbcc6
Parents: 7b95e2e
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Oct 22 20:10:42 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Tue Oct 22 20:10:42 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 5 +-
share/doc/src/contents.rst | 1 +
share/doc/src/install/unix.rst | 3 ++
share/doc/src/troubleshooting.rst | 76 +++++++++++++++++++++++++++++++
share/doc/templates/pages/index.html | 9 ++++
5 files changed, 93 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/bdf38a98/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index c4298d3..ee1062a 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -167,6 +167,7 @@ html_files = \
html/_sources/experimental.txt \
html/_sources/externals.txt \
html/_sources/json-structure.txt \
+ html/_sources/troubleshooting.txt \
html/_static/ajax-loader.gif \
html/_static/basic.css \
html/_static/comment-bright.png \
@@ -294,7 +295,8 @@ html_files = \
html/json-structure.html \
html/objects.inv \
html/search.html \
- html/searchindex.js
+ html/searchindex.js \
+ html/troubleshooting.html
if BUILD_HTML
html_files_build = $(html_files)
@@ -435,6 +437,7 @@ src_files = \
../src/contributing.rst \
../src/externals.rst \
../src/json-structure.rst \
+ ../src/troubleshooting.rst \
../src/conf.py
src_files_html = \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/bdf38a98/share/doc/src/contents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/contents.rst b/share/doc/src/contents.rst
index 4395f92..824f708 100644
--- a/share/doc/src/contents.rst
+++ b/share/doc/src/contents.rst
@@ -20,6 +20,7 @@
intro/index
install/index
+ troubleshooting
config/index
replication/index
maintenance/index
http://git-wip-us.apache.org/repos/asf/couchdb/blob/bdf38a98/share/doc/src/install/unix.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/install/unix.rst b/share/doc/src/install/unix.rst
index da4e5bd..39fa9da 100644
--- a/share/doc/src/install/unix.rst
+++ b/share/doc/src/install/unix.rst
@@ -177,6 +177,9 @@ To check that everything has worked, point your web browser to::
From here you should run the test suite in Firefox.
+
+.. _install/unix/security:
+
Security Considerations
-----------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/bdf38a98/share/doc/src/troubleshooting.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/troubleshooting.rst b/share/doc/src/troubleshooting.rst
new file mode 100644
index 0000000..f28646d
--- /dev/null
+++ b/share/doc/src/troubleshooting.rst
@@ -0,0 +1,76 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+
+.. Having single file for all type of issues should motivate us to keep their
+.. amount as small as possible. At least we should try to (:
+
+.. _troubleshooting:
+
+===============
+Troubleshooting
+===============
+
+All known issues could be divided into three groups:
+
+- When CouchDB won't build or be installed
+- When CouchDB installed, but won't start
+- When CouchDB returns some error during runtime
+
+
+CouchDB Won't Build
+===================
+
+Make sure that you have follow the :ref:`installation guide <install>` for your
+operation system.
+
+
+CouchDB Won't Start
+===================
+
+First of all, make sure that CouchDB's service user (``couchdb`` by default)
+has read and write permissions to the next directories and their files:
+
+#. :file:`(install_root)/etc/couchdb/`
+#. :file:`(install_root)/var/lib/couchdb/`
+#. :file:`(install_root)/var/log/couchdb/`
+#. :file:`(install_root)/var/run/couchdb/`
+
+See :ref:`install/unix/security` for more information about required
+permissions.
+
+The second good tip that is in case of some problem to run CouchDB in shell
+under ``couchdb`` user. This makes sure that you'll get the same behaviour as
+service init script and you'll not break permissions because of running commands
+as ``root`` user. Some distributions sets :file:`/sbin/nologin` shell for
+``couchdb`` user -- you have to change it to :file:`/bin/bash` or similar
+while fixing things (don't forget to change it back when you've done!)
+
+
+CouchDB Won't Work
+==================
+
+These issues might occurs when you working with CouchDB and encounters some
+unexpectable or unwanted behavior from CouchDB side. While fixing of this issue
+may takes for some time (or it may be even not fixed by some reasons) there
+you may found solutions to workaround them.
+
+
+There Is No My Issue Solution
+=============================
+
+Feel free to `open an issue`_ or mail to `mailing list`_ (`subscription`_ is
+required) with your issue description. *Hope that we could help with it*!
+
+.. _open an issue: https://issues.apache.org/jira/secure/CreateIssue!default.jspa
+.. _mailing list: mailto:user@couchdb.apache.org
+.. _subscription: mailto:user-subscribe@couchdb.apache.org
http://git-wip-us.apache.org/repos/asf/couchdb/blob/bdf38a98/share/doc/templates/pages/index.html
----------------------------------------------------------------------
diff --git a/share/doc/templates/pages/index.html b/share/doc/templates/pages/index.html
index 7eadda9..46b7703 100644
--- a/share/doc/templates/pages/index.html
+++ b/share/doc/templates/pages/index.html
@@ -155,6 +155,15 @@ specific language governing permissions and limitations under the License.
how to take care of your CouchDB
</span>
</p>
+ <p class="biglink">
+ <a class="biglink" href="{{ pathto("troubleshooting") }}">
+ Troubleshooting
+ </a>
+ <br />
+ <span class="linkdescr">
+ solve all the known problems!
+ </span>
+ </p>
</td>
</tr>
</table>