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 <[email protected]> Authored: Tue Oct 22 20:10:42 2013 +0400 Committer: Alexander Shorin <[email protected]> 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:[email protected] +.. _subscription: mailto:[email protected] 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>
