You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by je...@apache.org on 2015/03/06 13:35:25 UTC
[18/26] allura git commit: [#7835] Restructured the docs and updated
the theme.
[#7835] Restructured the docs and updated the theme.
Project: http://git-wip-us.apache.org/repos/asf/allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/allura/commit/ae5d2746
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/ae5d2746
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/ae5d2746
Branch: refs/heads/ib/7830
Commit: ae5d2746dc48e0173005225ae0f319e60d3d5190
Parents: 132cf7e
Author: Heith Seewald <hs...@slashdotmedia.com>
Authored: Mon Feb 23 04:05:38 2015 +0000
Committer: Dave Brondsema <da...@brondsema.net>
Committed: Tue Mar 3 16:00:59 2015 -0500
----------------------------------------------------------------------
Allura/allura/model/project.py | 11 +-
Allura/allura/webhooks.py | 6 +-
Allura/development.ini | 2 +-
Allura/docs/_static/images/messages.png | Bin 118641 -> 284938 bytes
Allura/docs/administration.rst | 114 ---------
Allura/docs/api/index.rst | 27 ++
Allura/docs/conf.py | 23 +-
Allura/docs/contributing.rst | 206 ----------------
Allura/docs/development/contributing.rst | 210 ++++++++++++++++
Allura/docs/development/extending.rst | 120 +++++++++
Allura/docs/development/external.rst | 36 +++
Allura/docs/development/index.rst | 30 +++
Allura/docs/development/testing.rst | 80 ++++++
Allura/docs/extending.rst | 116 ---------
Allura/docs/faq.rst | 68 ------
Allura/docs/getting_started/about.rst | 49 ++++
Allura/docs/getting_started/administration.rst | 115 +++++++++
Allura/docs/getting_started/index.rst | 32 +++
Allura/docs/getting_started/installation.rst | 107 ++++++++
Allura/docs/getting_started/scm_host.rst | 241 ++++++++++++++++++
Allura/docs/getting_started/scm_host_ssh.rst | 203 +++++++++++++++
Allura/docs/getting_started/using.rst | 64 +++++
Allura/docs/guides/email.rst | 69 ------
Allura/docs/guides/message_bus.rst | 97 --------
Allura/docs/guides/permissions.rst | 60 -----
Allura/docs/guides/scm.rst | 151 ------------
Allura/docs/index.rst | 77 +-----
Allura/docs/installation.rst | 108 --------
Allura/docs/intro.rst | 41 ----
Allura/docs/online.rst | 54 ----
Allura/docs/platform.rst | 118 ---------
Allura/docs/platform/email.rst | 71 ++++++
Allura/docs/platform/index.rst | 30 +++
Allura/docs/platform/message_bus.rst | 101 ++++++++
Allura/docs/platform/permissions.rst | 64 +++++
Allura/docs/platform/platform.rst | 137 +++++++++++
Allura/docs/platform/platform_tour.rst | 258 ++++++++++++++++++++
Allura/docs/platform/scm.rst | 150 ++++++++++++
Allura/docs/platform_tour.rst | 257 -------------------
Allura/docs/scm_host.rst | 236 ------------------
Allura/docs/scm_host_ssh.rst | 197 ---------------
Allura/docs/tutorials/testing.rst | 76 ------
Allura/docs/using.rst | 58 -----
INSTALL.markdown | 4 +-
requirements.txt | 1 +
45 files changed, 2163 insertions(+), 2112 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/allura/model/project.py
----------------------------------------------------------------------
diff --git a/Allura/allura/model/project.py b/Allura/allura/model/project.py
index 42e8e8d..b66ecec 100644
--- a/Allura/allura/model/project.py
+++ b/Allura/allura/model/project.py
@@ -690,14 +690,15 @@ class Project(SearchIndexable, MappedClass, ActivityNode, ActivityObject):
return roles
def install_apps(self, apps_params):
- '''
- Install many apps at once. Better than doing individually if you expect
+ """ Install many apps at once.
+
+ Better than doing individually if you expect
default name conflicts (e.g. "code" for both git & svn), by using the
tool_label value.
- :param list apps_params: list of dicts, where each dict is the args used
- in install_app()
- '''
+ :param list apps_params: list of dicts, where each dict is the args used in install_app()
+ """
+
# determine all the mount points
mount_points = dict()
for app_params in apps_params:
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/allura/webhooks.py
----------------------------------------------------------------------
diff --git a/Allura/allura/webhooks.py b/Allura/allura/webhooks.py
index d41f477..c42be86 100644
--- a/Allura/allura/webhooks.py
+++ b/Allura/allura/webhooks.py
@@ -409,9 +409,9 @@ class WebhookSender(object):
"""Post a task that will send webhook payload
:param params_or_list: dict with keyword parameters to be passed to
- :meth:`get_payload` or a list of such dicts. If it's a list for each
- element appropriate payload will be submitted, but limit will be
- enforced only once for each webhook.
+ :meth:`get_payload` or a list of such dicts. If it's a list for each
+ element appropriate payload will be submitted, but limit will be
+ enforced only once for each webhook.
"""
if not isinstance(params_or_list, list):
params_or_list = [params_or_list]
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/development.ini
----------------------------------------------------------------------
diff --git a/Allura/development.ini b/Allura/development.ini
index c581808..ba06cc5 100644
--- a/Allura/development.ini
+++ b/Allura/development.ini
@@ -209,7 +209,7 @@ scm.host.rw.hg = /srv/hg$path
scm.host.ro.svn = file:///srv/svn$path/
scm.host.rw.svn = file:///srv/svn$path/
-# SCM settings for chroot + ldap configuration. See Allura/docs/scm_host.rst
+# SCM settings for chroot + ldap configuration. See Allura/docs/getting_started/scm_host.rst
# scm.host.ro.git = git://git.localhost$path
# scm.host.rw.git = ssh://$username@localhost:8022/scm-repo$path
# scm.host.ro.hg = http://hg.localhost$path
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/_static/images/messages.png
----------------------------------------------------------------------
diff --git a/Allura/docs/_static/images/messages.png b/Allura/docs/_static/images/messages.png
index 14c63ad..2f88b34 100644
Binary files a/Allura/docs/_static/images/messages.png and b/Allura/docs/_static/images/messages.png differ
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/administration.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/administration.rst b/Allura/docs/administration.rst
deleted file mode 100644
index b4f69f5..0000000
--- a/Allura/docs/administration.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you 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.
-
-Administration
-=================
-
-Commands, Scripts, and Tasks
-----------------------------
-
-Allura has many `paster` commands and `paster` scripts that can be run from the
-server commandline to administrate Allura. There are also tasks that can be
-run through the `taskd` system. New tasks can be submitted via the web at
-/nf/admin/task_manager Some paster commands and scripts have been set up
-so that they are runnable as tasks too, giving you the convenience of starting
-them through the web and letting `taskd` execute them, rather than from a server
-shell.
-
-Commands can be discovered and run via the `paster` command when you are in the
-'Allura' directory that has your .ini file. For example::
-
- (env-allura) Allura$ paster help
- ... all commands listed here ...
-
- (env-allura) Allura$ paster create-neighborhood --help
- ... specific command help ...
-
- (env-allura) Allura$ paster create-neighborhood development.ini myneighborhood myuser ...
-
-
-Scripts are in the `scripts/` directory and run via `paster script`. An extra
-`--` is required to separate script arguments from paster arguments. Example::
-
- (env-allura) Allura$ paster script development.ini ../scripts/create-allura-sitemap.py -- --help
- ... help output ...
-
- (env-allura) Allura$ paster script development.ini ../scripts/create-allura-sitemap.py -- -u 100
-
-TODO: explain important scripts, commands
-
-Tasks can be run via the web interface at /nf/admin/task_manager You must know
-the full task name, e.g. `allura.tasks.admin_tasks.install_app` You can
-optionally provide a username and project and app which will get set on the
-current context (`c`). You should specify what args and kwargs will be passed
-as parameters to the task. They are specified in JSON format on the form.
-
-See the listing of :mod:`some available tasks <allura.tasks.admin_tasks>`.
-
-TODO: explain how to run scripttasks and commandtasks
-
-
-Client Scripts
---------------
-
-Allura includes some client scripts that use Allura APIs and do not have to be run
-from an Allura server. They do require various python packages to be installed
-and possibly a local Allura codebase set up.
-
-One such script is `wiki-copy.py` which reads the wiki pages from one Allura wiki
-instance and uploads them to another Allura wiki instance. It can be run as:
-
-.. code-block:: console
-
- $ python scripts/wiki-copy.py --help
-
-
-Site Notifications
-------------------
-
-Allura has support for site-wide notifications that appear below the site header,
-but there is currently no UI for managing them. They can easily be inserted via
-manual mongo queries, however:
-
-.. code-block:: console
-
- > db.site_notification.insert({
- ... active: true,
- ... impressions: 10,
- ... content: 'You can now reimport exported project data.'
- ... })
-
-This will create a notification that will be shown for 10 page views or until the
-user closes it manually. An `impressions` value of 0 will show the notification
-indefinitely (until closed). The notification content can contain HTML. Only the
-most recent notification will be shown, unless it has `active:false`, in which case
-no notification will be shown.
-
-
-Using Projects and Tools
-------------------------
-
-We currently don't have any further documentation for basic operations of managing
-users, projects, and tools on Allura. However, SourceForge has help docs that cover
-these functions https://sourceforge.net/p/forge/documentation/Docs%20Home/ Note
-that this documentation also covers some SourceForge features that are not part of Allura.
-
-
-Public API Documentation
-------------------------
-
-Allura's web api is currently documented at https://sourceforge.net/p/forge/documentation/Allura%20API/
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/api/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/api/index.rst b/Allura/docs/api/index.rst
new file mode 100644
index 0000000..2103410
--- /dev/null
+++ b/Allura/docs/api/index.rst
@@ -0,0 +1,27 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+**********
+Allura API
+**********
+
+
+.. toctree::
+ :maxdepth: 3
+ :glob:
+
+ *
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/conf.py
----------------------------------------------------------------------
diff --git a/Allura/docs/conf.py b/Allura/docs/conf.py
index 03ad27f..c201b9c 100644
--- a/Allura/docs/conf.py
+++ b/Allura/docs/conf.py
@@ -37,6 +37,8 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+import os
+
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx',
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig']
@@ -99,21 +101,30 @@ exclude_trees = ['_build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
+# A list of document names that are present, but not currently included in the toctree.
+unused_docs = 'getting_started/scm_host_ssh.rst'
+
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'nature'
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd: # only import and set the theme if we're building docs locally
+ import sphinx_rtd_theme
+ html_theme = 'sphinx_rtd_theme'
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-html_theme_options = {
- 'sidebarwidth': 280, # default 230 (px)
-}
+# html_theme_options = {
+# 'sidebarwidth': 280, # default 230 (px)
+# }
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/contributing.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/contributing.rst b/Allura/docs/contributing.rst
deleted file mode 100644
index e899d05..0000000
--- a/Allura/docs/contributing.rst
+++ /dev/null
@@ -1,206 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you 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.
-
-Contributing to Allura
-======================
-For developers interested in hacking on Allura or its components, this guide
-will (hopefully) be a roadmap to help you get started and guide you on your
-way.
-
-Getting Help
-------------
-Along the way, you will no doubt have questions that aren't addressed here.
-For help, you can get in touch with other Allura developers on the developer
-mailing list (dev@allura.apache.org) or in the #allura channel on
-the Freenode IRC network.
-
-Installing Allura
------------------
-Before hacking on Allura, you'll need to get an Allura instance up and running
-so you can see and test the changes you make. You can install Allura from
-scratch, or by using our pre-built Vagrant image. Instructions for these
-approaches can be found here:
-
-* `Install from scratch <https://forge-allura.apache.org/p/allura/git/ci/master/tree/INSTALL.markdown>`_
-* `Install from Vagrant image <https://forge-allura.apache.org/p/allura/wiki/Install%20and%20Run%20Allura%20-%20Vagrant/>`_
-
-Managing Services
------------------
-Allura is comprised of a handful of separate services, all of which must be
-running in order for the system to be fully functional. These services (and
-how to start them) are covered in the install documentation, but are mentioned
-again here simply to reiterate the components of a complete Allura system.
-
-External services:
-
-* MongoDB - database
-* Solr - searching/indexing
-
-Allura services:
-
-* Web server - the Allura web application
-* :doc:`Taskd <guides/message_bus>` - background task daemon
-* Inbound email handler - processes email sent to the Allura instance (e.g.,
- a reply to a ticket notification email)
-
-Logging
--------
-The logs for Allura services can be found in ``/var/log/allura/``.
-The most important of these is ``allura.log``, as it will contain log messages
-for all Allura application code.
-
-Technology Stack
-----------------
-`MongoDB <http://www.mongodb.org/>`_ - Allura stores all of its data in MongoDB.
-If you're new to MongoDB, you'll want to keep the `reference docs
-<http://docs.mongodb.org/manual/reference/>`_ handy until you're familiar with
-basic query operations and syntax.
-
-`Solr <http://lucene.apache.org/solr/>`_ - Allura artifact data is indexed into
-Solr so that it can be searched. In general, you won't need to know much about
-Solr in order to work on Allura.
-
-`Turbogears <http://turbogears.org/>`_ - Allura is built on the TurboGears web
-framework. Understanding `TG controller basics <http://turbogears.readthedocs.org/en/tg2.3.0b2/turbogears/controllers.html>`_
-and `object dispatch <http://turbogears.readthedocs.org/en/tg2.3.0b2/turbogears/objectdispatch.html>`_,
-TurboGears' mechanism for routing an HTTP request to the code that should handle
-it, are critical for understanding how a request is handled by Allura.
-
-`Ming <http://merciless.sourceforge.net/index.html>`_ - Allura interfaces with
-MongoDB through Ming, a library which provides an Object Document Mapper for
-MongoDB. Fortunately, the query syntax is mostly identical to that of
-native MongoDB, so the learning curve is pretty flat.
-
-`EasyWidgets <http://easywidgets.pythonisito.com/index.html>`_ - An HTML template
-and form validation library used by Allura. The learning curve on EasyWidgets
-is, ironically, not easy. Be prepared to dig into the source if you want to
-do something complicated with EW. Fortunately, there are lots of exmaples in
-the Allura source already.
-
-`Jinja <http://jinja.pocoo.org/>`_ - HTML template library used by Allura.
-
-If you want to work on the front end of Allura, you'll also need some CSS and
-Javascript skills, and basic knowledge of JQuery.
-
-Finding Something to Work On
-----------------------------
-Tickets that are relatively simple and good for new contributors have a
-"bitesize" label, and can be found here:
-https://sourceforge.net/p/allura/tickets/search/?q=labels%3Abitesize
-
-Find one that looks good, and leave a comment on the ticket or mailing list
-to let us know you're working on it. If you get stuck, remember that we're
-available to help on the mailing list or IRC.
-
-Code Organization
------------------
-The core Allura platform code is in the ``Allura/`` directory in the top-level of the
-repo. The ``Forge*/`` directories contain Allura "tools" - plugins that extend the
-core platform. For an overview of the platform and services it provides, read
-the :doc:`Platform Tour <platform_tour>` documentation. If you're interested in
-developing a new Allura plugin, you may find this `blog series <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/>`_
-helpful.
-
-Tracing a Request
------------------
-Whether you're fixing a bug or adding a new feature, one of your first
-questions will be, "Where is the code that is handling this request (or serving
-this page)?" For a new contributor, answering this question can be surprisingly
-challenging. Here are some tips to help you out:
-
-1. The root controller for the entire application is in
-``Allura/allura/controllers/root.py`` - dispatch for *every* request begins
-here. It is possible (albeit difficult) to trace the path your request
-will take through the code from this starting point if you have a
-thorough knowledge of Turbogears' request dispatch mechanics. But, nobody
-wants to do this if they can avoid it.
-
-2. Is the page being served part of a tool (e.g. Ticket Tracker, Wiki, etc)?
-Most of the time, the answer is yes. If you know which tool is handling the
-request, you can skip right to the root controller for that tool. To find the
-root controller, first find the main entry point for the tool, which is defined
-in the ``[allura]`` section of the tool's ``setup.py`` file. So, for example,
-if you know the request is being handled by a Ticket Tracker, look in
-``ForgeTracker/setup.py`` and you'll see that that its entry point is
-``forgetracker.tracker_main:ForgeTrackerApp``. Each Allura tool instance
-defines a ``root`` attribute which is its root controller. So once you've found
-the main tool class, you can find its root controller and begin tracing your
-request from there.
-
-3. Search for things! ``grep`` and equivalents are your friends. If you're
-looking at an html page and want to find the controller code for it, try
-searching the code base for some (static) text on the page. If your search
-successfully turns up an html page, search again on the name of the html file.
-There's a good change you'll find the controller method that renders that page.
-
-Interactive Debugging
----------------------
-If you've never used ``ipdb`` before, you'll find it's a great tool for
-interactive debugging of Python code. In order to use ``ipdb`` to debug Allura,
-you'll first need to make sure that the process you're debugging is running in
-the foreground. In most cases you'll be debugging either the web app process
-or the taskd (background worker) process.
-
-First, make sure sure ipdb is installed in your virtual environment::
-
- pip install ipdb
-
-Then, find the line of code where you want to start the interactive debugger,
-and insert this line above it::
-
- import ipdb; ipdb.set_trace()
-
-Now, kill any running web or taskd procs and restart them in the
-foreground::
-
- cd Allura
- # web
- pkill "paster serve" && paster serve --reload ../development.ini
- # taskd
- pkill "paster taskd" && paster taskd ../development.ini
-
-Make a request to the web app, and when your line of code is hit, a debug
-session will start on the console where the process is running.
-
-For more information about using ``pdb``, see the `official documentation
-<http://docs.python.org/2/library/pdb.html>`_.
-
-Testing
--------
-To run all the tests, execute ``./run_tests`` in the repo root. To run tests
-for a single package, for example ``forgetracker``::
-
- cd ForgeTracker && nosetests
-
-To learn more about the ``nose`` test runner, consult the `documentation
-<http://nose.readthedocs.org/en/latest/>`_.
-
-When writing code for Allura, don't forget that you'll need to also create
-tests that cover behaviour that you've added or changed. You may find this
-:doc:`short guide <tutorials/testing>` helpful.
-
-
-Submitting a Merge Request
---------------------------
-Before submitting a merge request, make sure your changes conform to our
-`contribution guidelines <https://forge-allura.apache.org/p/allura/wiki/Contributing%20Code/>`_.
-Once your changes are finished and tested, submit them to be merged back into
-the main repo:
-
-* Fork the main Allura repo from here: https://forge-allura.apache.org/p/allura/git/
-* Commit and push your changes to your fork
-* Submit a Merge Request from your fork
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/development/contributing.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/development/contributing.rst b/Allura/docs/development/contributing.rst
new file mode 100644
index 0000000..e96e5be
--- /dev/null
+++ b/Allura/docs/development/contributing.rst
@@ -0,0 +1,210 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+************
+Contributing
+************
+
+Contributing to Allura
+======================
+For developers interested in hacking on Allura or its components, this guide
+will (hopefully) be a roadmap to help you get started and guide you on your
+way.
+
+Getting Help
+------------
+Along the way, you will no doubt have questions that aren't addressed here.
+For help, you can get in touch with other Allura developers on the developer
+mailing list (dev@allura.apache.org) or in the #allura channel on
+the Freenode IRC network.
+
+Installing Allura
+-----------------
+Before hacking on Allura, you'll need to get an Allura instance up and running
+so you can see and test the changes you make. You can install Allura from
+scratch, or by using our pre-built Vagrant image. Instructions for these
+approaches can be found here:
+
+* `Install from scratch <https://forge-allura.apache.org/p/allura/git/ci/master/tree/INSTALL.markdown>`_
+* `Install from Vagrant image <https://forge-allura.apache.org/p/allura/wiki/Install%20and%20Run%20Allura%20-%20Vagrant/>`_
+
+Managing Services
+-----------------
+Allura is comprised of a handful of separate services, all of which must be
+running in order for the system to be fully functional. These services (and
+how to start them) are covered in the install documentation, but are mentioned
+again here simply to reiterate the components of a complete Allura system.
+
+External services:
+
+* MongoDB - database
+* Solr - searching/indexing
+
+Allura services:
+
+* Web server - the Allura web application
+* :doc:`Taskd <../platform/message_bus>` - background task daemon
+* Inbound email handler - processes email sent to the Allura instance (e.g.,
+ a reply to a ticket notification email)
+
+Logging
+-------
+The logs for Allura services can be found in ``/var/log/allura/``.
+The most important of these is ``allura.log``, as it will contain log messages
+for all Allura application code.
+
+Technology Stack
+----------------
+`MongoDB <http://www.mongodb.org/>`_ - Allura stores all of its data in MongoDB.
+If you're new to MongoDB, you'll want to keep the `reference docs
+<http://docs.mongodb.org/manual/reference/>`_ handy until you're familiar with
+basic query operations and syntax.
+
+`Solr <http://lucene.apache.org/solr/>`_ - Allura artifact data is indexed into
+Solr so that it can be searched. In general, you won't need to know much about
+Solr in order to work on Allura.
+
+`Turbogears <http://turbogears.org/>`_ - Allura is built on the TurboGears web
+framework. Understanding `TG controller basics <http://turbogears.readthedocs.org/en/tg2.3.0b2/turbogears/controllers.html>`_
+and `object dispatch <http://turbogears.readthedocs.org/en/tg2.3.0b2/turbogears/objectdispatch.html>`_,
+TurboGears' mechanism for routing an HTTP request to the code that should handle
+it, are critical for understanding how a request is handled by Allura.
+
+`Ming <http://merciless.sourceforge.net/index.html>`_ - Allura interfaces with
+MongoDB through Ming, a library which provides an Object Document Mapper for
+MongoDB. Fortunately, the query syntax is mostly identical to that of
+native MongoDB, so the learning curve is pretty flat.
+
+`EasyWidgets <http://easywidgets.pythonisito.com/index.html>`_ - An HTML template
+and form validation library used by Allura. The learning curve on EasyWidgets
+is, ironically, not easy. Be prepared to dig into the source if you want to
+do something complicated with EW. Fortunately, there are lots of exmaples in
+the Allura source already.
+
+`Jinja <http://jinja.pocoo.org/>`_ - HTML template library used by Allura.
+
+If you want to work on the front end of Allura, you'll also need some CSS and
+Javascript skills, and basic knowledge of JQuery.
+
+Finding Something to Work On
+----------------------------
+Tickets that are relatively simple and good for new contributors have a
+"bitesize" label, and can be found here:
+https://sourceforge.net/p/allura/tickets/search/?q=labels%3Abitesize
+
+Find one that looks good, and leave a comment on the ticket or mailing list
+to let us know you're working on it. If you get stuck, remember that we're
+available to help on the mailing list or IRC.
+
+Code Organization
+-----------------
+The core Allura platform code is in the ``Allura/`` directory in the top-level of the
+repo. The ``Forge*/`` directories contain Allura "tools" - plugins that extend the
+core platform. For an overview of the platform and services it provides, read
+the :doc:`Platform Tour <../platform/platform_tour>` documentation. If you're interested in
+developing a new Allura plugin, you may find this `blog series <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/>`_
+helpful.
+
+Tracing a Request
+-----------------
+Whether you're fixing a bug or adding a new feature, one of your first
+questions will be, "Where is the code that is handling this request (or serving
+this page)?" For a new contributor, answering this question can be surprisingly
+challenging. Here are some tips to help you out:
+
+1. The root controller for the entire application is in
+``Allura/allura/controllers/root.py`` - dispatch for *every* request begins
+here. It is possible (albeit difficult) to trace the path your request
+will take through the code from this starting point if you have a
+thorough knowledge of Turbogears' request dispatch mechanics. But, nobody
+wants to do this if they can avoid it.
+
+2. Is the page being served part of a tool (e.g. Ticket Tracker, Wiki, etc)?
+Most of the time, the answer is yes. If you know which tool is handling the
+request, you can skip right to the root controller for that tool. To find the
+root controller, first find the main entry point for the tool, which is defined
+in the ``[allura]`` section of the tool's ``setup.py`` file. So, for example,
+if you know the request is being handled by a Ticket Tracker, look in
+``ForgeTracker/setup.py`` and you'll see that that its entry point is
+``forgetracker.tracker_main:ForgeTrackerApp``. Each Allura tool instance
+defines a ``root`` attribute which is its root controller. So once you've found
+the main tool class, you can find its root controller and begin tracing your
+request from there.
+
+3. Search for things! ``grep`` and equivalents are your friends. If you're
+looking at an html page and want to find the controller code for it, try
+searching the code base for some (static) text on the page. If your search
+successfully turns up an html page, search again on the name of the html file.
+There's a good change you'll find the controller method that renders that page.
+
+Interactive Debugging
+---------------------
+If you've never used ``ipdb`` before, you'll find it's a great tool for
+interactive debugging of Python code. In order to use ``ipdb`` to debug Allura,
+you'll first need to make sure that the process you're debugging is running in
+the foreground. In most cases you'll be debugging either the web app process
+or the taskd (background worker) process.
+
+First, make sure sure ipdb is installed in your virtual environment::
+
+ pip install ipdb
+
+Then, find the line of code where you want to start the interactive debugger,
+and insert this line above it::
+
+ import ipdb; ipdb.set_trace()
+
+Now, kill any running web or taskd procs and restart them in the
+foreground::
+
+ cd Allura
+ # web
+ pkill "paster serve" && paster serve --reload ../development.ini
+ # taskd
+ pkill "paster taskd" && paster taskd ../development.ini
+
+Make a request to the web app, and when your line of code is hit, a debug
+session will start on the console where the process is running.
+
+For more information about using ``pdb``, see the `official documentation
+<http://docs.python.org/2/library/pdb.html>`_.
+
+Testing
+-------
+To run all the tests, execute ``./run_tests`` in the repo root. To run tests
+for a single package, for example ``forgetracker``::
+
+ cd ForgeTracker && nosetests
+
+To learn more about the ``nose`` test runner, consult the `documentation
+<http://nose.readthedocs.org/en/latest/>`_.
+
+When writing code for Allura, don't forget that you'll need to also create
+tests that cover behaviour that you've added or changed. You may find this
+:doc:`short guide <../development/testing>` helpful.
+
+
+Submitting a Merge Request
+--------------------------
+Before submitting a merge request, make sure your changes conform to our
+`contribution guidelines <https://forge-allura.apache.org/p/allura/wiki/Contributing%20Code/>`_.
+Once your changes are finished and tested, submit them to be merged back into
+the main repo:
+
+* Fork the main Allura repo from here: https://forge-allura.apache.org/p/allura/git/
+* Commit and push your changes to your fork
+* Submit a Merge Request from your fork
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/development/extending.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/development/extending.rst b/Allura/docs/development/extending.rst
new file mode 100644
index 0000000..e45b1c2
--- /dev/null
+++ b/Allura/docs/development/extending.rst
@@ -0,0 +1,120 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+*********
+Extending
+*********
+
+Extension APIs and Entry Points
+===============================
+
+There are many extension points to extending Allura. They all make themselves
+known to Allura via python entry points defined in ``setup.py``. Many are then
+available immediately. Others, such as authentication providers or themes, need
+to be specified in your ``.ini`` file, since you may only have one enabled at a time.
+
+The available extension points for Allura are:
+
+* :class:`allura.app.Application` (aka tool) and :class:`allura.app.Artifact`
+* :class:`allura.lib.plugin.ThemeProvider`
+* :class:`allura.lib.plugin.ProjectRegistrationProvider`
+* :class:`allura.lib.plugin.AuthenticationProvider`
+* :class:`allura.lib.plugin.UserPreferencesProvider`
+* :class:`allura.lib.plugin.AdminExtension`
+* :class:`allura.lib.plugin.SiteAdminExtension`
+* :class:`allura.lib.spam.SpamFilter`
+* ``site_stats`` in the root API data. Docs in :class:`allura.controllers.rest.RestController`
+* :mod:`allura.lib.package_path_loader` (for overriding templates)
+* ``[allura.timers]`` functions which return a list or single :class:`timermiddleware.Timer` which will be included in stats.log timings
+* :mod:`allura.ext.user_profile`
+* ``[allura.middleware]`` classes, which are standard WSGI middleware. They will receive the ``app`` instance and a ``config`` dict as constructor parameters.
+ The middleware will be used for all requests. By default the middleware wraps the base app directly and other middleware wrap around it.
+ If your middleware needs to wrap around the other Allura middleware (except error handling), set ``when = 'outer'`` on your middleware.
+* :class:`allura.webhooks.WebhookSender`
+
+A listing of available 3rd-party extensions is at https://forge-allura.apache.org/p/allura/wiki/Extensions/
+
+To disable any Allura entry point, simply add an entry in your ``.ini`` config file
+with names and values corresponding to entry points defined in any ``setup.py`` file.
+For example if you have ForgeImporter set up, but want to disable the google code importers:
+
+.. code-block:: ini
+
+ disable_entry_points.allura.project_importers = google-code
+ disable_entry_points.allura.importers = google-code-tracker, google-code-repo
+
+Other entry points are used to provide ``paster`` commands and ``easy_widget`` configuration,
+which are not part of Allura but are used by Allura.
+
+
+Event Handlers
+==============
+
+Another way to extend Allura is set up event handlers to respond to Allura events.
+There is documentation and examples at :ref:`events`.
+
+The events that allura publishes are:
+
+* project_created
+* project_updated
+* repo_cloned
+* repo_refreshed
+* repo_clone_task_failed
+* trove_category_created
+* trove_category_updated
+* trove_category_deleted
+
+
+Markdown Macros
+===============
+
+Most text inputs in Allura accept Markdown text which is parsed and turned into
+HTML before being rendered. The Markdown text may contain "macros" - custom
+commands which extend the Markdown language. Here's an example of a macro
+that comes with Allura::
+
+ [[project_admins]]
+
+Include this macro in a wiki page or other Markdown content, and when rendered
+it will be replaced by an actual list of the project's admin users.
+
+Extending Allura with your own macros is simple, requiring two basic steps:
+
+1. Decide on a name for your macro, then create a function with that name, and
+ decorate it with the `macro()` decorator from Allura. The function can
+ accept keyword arguments, and must return text or HTML. For example::
+
+ from allura.lib.macro import macro
+
+ @macro()
+ def hello(name='World'):
+ return "<p>Hello {}!</p>".format(name)
+
+2. Add an entry point for your macro to the `setup.py` for your package::
+
+ [allura.macros]
+ hello_macro = mypkg.mymodule:hello
+
+Note that the key name (`hello_macro` in this case) doesn't matter - the macro
+is named after the function name. Our example macro could be used in a couple
+ways::
+
+ [[hello]]
+ [[hello name=Universe]]
+
+For more help with macros, consult the source code for the macros that ship
+with Allura. You can find them in the `allura.lib.macro` package.
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/development/external.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/development/external.rst b/Allura/docs/development/external.rst
new file mode 100644
index 0000000..6346bbf
--- /dev/null
+++ b/Allura/docs/development/external.rst
@@ -0,0 +1,36 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+***************************
+Writing an Allura-based app
+***************************
+
+External links
+ * `Getting Started <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/06/part-1-getting-started/>`_
+ * `Forms, Artifacts, and Testing <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/06/part-2-creating-our-first-paste/>`_
+ * `Adding a Custom Icon <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/12/part-3-adding-a-custom-icon/>`_
+ * `Adding a Sidebar Menu <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/12/adding-a-sidebar-menu/>`_
+ * `Adding Custom CSS <https://sourceforge.net/u/vansteenburgh/allura-plugin-development/2013/12/part-5-adding-custom-css/>`_
+
+
+Generated API docs, useful for browsing through the code, viewing inheritance, etc:
+
+* http://allura.sourceforge.net/epydoc/
+
+Our project page, including tickets, discussion forums, etc.:
+
+* https://allura.apache.org/
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/development/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/development/index.rst b/Allura/docs/development/index.rst
new file mode 100644
index 0000000..1e15906
--- /dev/null
+++ b/Allura/docs/development/index.rst
@@ -0,0 +1,30 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+***********************
+Development & community
+***********************
+
+
+.. toctree::
+ :maxdepth: 3
+
+ extending
+ contributing
+ external
+ testing
+
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/development/testing.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/development/testing.rst b/Allura/docs/development/testing.rst
new file mode 100644
index 0000000..bcff43f
--- /dev/null
+++ b/Allura/docs/development/testing.rst
@@ -0,0 +1,80 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+*****************
+Testing in Allura
+*****************
+
+Writing Tests for Allura Tools
+==============================
+
+Testing the controllers and models of an Allura tool is fairly
+straightforward. Generally, you should follow the example of tests in the
+`allura/tests/functional` directory for controller tests and
+`allura.tests.model` for model tests. For functional tests, the Allura platform
+provides a convenient "test harness" :class:`allura.controllers.test.TestController` controller
+class which is used as the application root for the
+:class:`allura.tests.TestController` class.
+
+In order to test your new tool controllers, you simply need to use the `self.app.get()`
+and `self.app.post()` methods of your test controller. The test harness makes
+all the tools available in the system available under the URL /*entry point
+name*/. So to test the :mod:`allura.ext.project_home` tool, for instance, we
+need only write the following::
+
+ from allura.tests import TestController
+
+ class TestProjectHome(TestController):
+
+ def test_home(self):
+ r = self.app.get('/home/')
+
+Whenever you use the :class:`allura.tests.TestController` app property, the
+test harness sets up the context so that `c.project` is always the
+`projects/test` project and whichever tool name you request is mounted at its
+entry point (so the Wiki tool will be mounted at /Wiki/). `c.user` is always
+set to the `test-admin` user to avoid authentication issues.
+
+The framework used to generate the WSGI environment for testing your tools is
+provided by the `WebTest <http://pythonpaste.org/webtest/>`_ module, where you can
+find further documentation for the `.get()` and `.post()` methods.
+
+Testing Allura models is also straightforward, though you will often
+need to setup pylons global objects before your test. If the code under test
+uses pylons globals (like `g` and `c`), but your test doesn't require the
+fully-loaded wsgi app, you can do something like this:
+
+.. code-block:: python
+
+ from pylons import tmpl_context as c
+
+ from alluratest.controller import setup_unit_test
+ from allura.lib import helpers a h
+ from allura import model as M
+
+ def setUp():
+ # set up pylons globals
+ setup_unit_test()
+
+ # set c.project and c.app
+ h.set_context('test', 'wiki', neighborhood='Projects'):
+ c.user = M.User.query.get(username='test-admin')
+
+Testing the tasks and events is similar to testing models. Generally, you will
+simply want to call your `@task` and `@event_handler` methods directly rather
+than setting up a full mocking infrastructure, though it is possible to use the
+MonQTask model in the allura model if you wish to do more functional/integration testing.
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/extending.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/extending.rst b/Allura/docs/extending.rst
deleted file mode 100644
index 825bcbd..0000000
--- a/Allura/docs/extending.rst
+++ /dev/null
@@ -1,116 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you 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.
-
-Extension APIs and Entry Points
-===============================
-
-There are many extension points to extending Allura. They all make themselves
-known to Allura via python entry points defined in ``setup.py``. Many are then
-available immediately. Others, such as authentication providers or themes, need
-to be specified in your ``.ini`` file, since you may only have one enabled at a time.
-
-The available extension points for Allura are:
-
-* :class:`allura.app.Application` (aka tool) and :class:`allura.app.Artifact`
-* :class:`allura.lib.plugin.ThemeProvider`
-* :class:`allura.lib.plugin.ProjectRegistrationProvider`
-* :class:`allura.lib.plugin.AuthenticationProvider`
-* :class:`allura.lib.plugin.UserPreferencesProvider`
-* :class:`allura.lib.plugin.AdminExtension`
-* :class:`allura.lib.plugin.SiteAdminExtension`
-* :class:`allura.lib.spam.SpamFilter`
-* ``site_stats`` in the root API data. Docs in :class:`allura.controllers.rest.RestController`
-* :mod:`allura.lib.package_path_loader` (for overriding templates)
-* ``[allura.timers]`` functions which return a list or single :class:`timermiddleware.Timer` which will be included in stats.log timings
-* :mod:`allura.ext.user_profile`
-* ``[allura.middleware]`` classes, which are standard WSGI middleware. They will receive the ``app`` instance and a ``config`` dict as constructor parameters.
- The middleware will be used for all requests. By default the middleware wraps the base app directly and other middleware wrap around it.
- If your middleware needs to wrap around the other Allura middleware (except error handling), set ``when = 'outer'`` on your middleware.
-* :class:`allura.webhooks.WebhookSender`
-
-A listing of available 3rd-party extensions is at https://forge-allura.apache.org/p/allura/wiki/Extensions/
-
-To disable any Allura entry point, simply add an entry in your ``.ini`` config file
-with names and values corresponding to entry points defined in any ``setup.py`` file.
-For example if you have ForgeImporter set up, but want to disable the google code importers:
-
-.. code-block:: ini
-
- disable_entry_points.allura.project_importers = google-code
- disable_entry_points.allura.importers = google-code-tracker, google-code-repo
-
-Other entry points are used to provide ``paster`` commands and ``easy_widget`` configuration,
-which are not part of Allura but are used by Allura.
-
-
-Event Handlers
-==============
-
-Another way to extend Allura is set up event handlers to respond to Allura events.
-There is documentation and examples at :ref:`events`.
-
-The events that allura publishes are:
-
-* project_created
-* project_updated
-* repo_cloned
-* repo_refreshed
-* repo_clone_task_failed
-* trove_category_created
-* trove_category_updated
-* trove_category_deleted
-
-
-Markdown Macros
-===============
-
-Most text inputs in Allura accept Markdown text which is parsed and turned into
-HTML before being rendered. The Markdown text may contain "macros" - custom
-commands which extend the Markdown language. Here's an example of a macro
-that comes with Allura::
-
- [[project_admins]]
-
-Include this macro in a wiki page or other Markdown content, and when rendered
-it will be replaced by an actual list of the project's admin users.
-
-Extending Allura with your own macros is simple, requiring two basic steps:
-
-1. Decide on a name for your macro, then create a function with that name, and
- decorate it with the `macro()` decorator from Allura. The function can
- accept keyword arguments, and must return text or HTML. For example::
-
- from allura.lib.macro import macro
-
- @macro()
- def hello(name='World'):
- return "<p>Hello {}!</p>".format(name)
-
-2. Add an entry point for your macro to the `setup.py` for your package::
-
- [allura.macros]
- hello_macro = mypkg.mymodule:hello
-
-Note that the key name (`hello_macro` in this case) doesn't matter - the macro
-is named after the function name. Our example macro could be used in a couple
-ways::
-
- [[hello]]
- [[hello name=Universe]]
-
-For more help with macros, consult the source code for the macros that ship
-with Allura. You can find them in the `allura.lib.macro` package.
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/faq.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/faq.rst b/Allura/docs/faq.rst
deleted file mode 100644
index 0c26b43..0000000
--- a/Allura/docs/faq.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you 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.
-
-Why not improve existing tools like Trac, Redmine or Bugzilla?
---------------------------------------------------------------
-
-One word. Scalability.
-
-Ok, two words. Scalability and Performance
-
-Ok, three words: Scalability, Performance, and Flexibility
-
-Seriously though, we didn't think that any of the existing systems have
-actually hit the right usability, scalability, or flexibility targets that
-we needed to hit, and we knew that it would be a **lot** of work to get
-any of them to do what we needed.
-
-But we knew e-mail integration was going to be a big deal to our forge,
-so we did take a long look at Roundup, which is a very well designed
-system build from the ground up around the idea of e-mail integration.
-
-If you were so inspired by Roundup, why not just use it?
---------------------------------------------------------
-
-We liked the flexible schema system provided by Roundup's HyperTable layer,
-but thought that native MongoDB bindings were both cleaner, faster, and
-ultimately more powerful.
-
-Sure we sacrifice the flexibility of Roundup's
-backend, but our main goal is to make usable, high performance system,
-not to maximize the number of backend storages systems supported.
-
-Why create all the apps as plugins?
------------------------------------
-
-We know that some projects are going to want more locked down
-access controls in their bug trackers, or more workflow based
-processes. These things are inevitable, and we really do want
-to support them, but at the same time they are going to conflict
-with the way many other projects want to work.
-
-Building a plugin (tool in Allura terms) system, and standard
-integration points makes it possible to serve everybody in one
-way or another.
-
-Why not just allow web-based extensions?
-----------------------------------------
-
-We talked about this quite a bit, and decided that we could write local
-native tools more quickly and easily, and that we could build a
-local app tool that proxied out to an external webapp, and that
-we could provide a lot more flexibility by allowing custom
-external webapp proxies -- which brought us right back to local
-tools.
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/getting_started/about.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/about.rst b/Allura/docs/getting_started/about.rst
new file mode 100644
index 0000000..a96c0a9
--- /dev/null
+++ b/Allura/docs/getting_started/about.rst
@@ -0,0 +1,49 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+***********
+Why Allura?
+***********
+
+
+Rather than build yet another forge, we decided to do something new. We wanted to build a new kind of extensible forge, and a new set of highly integrated forge tools.
+
+
+Allura is an **open** platform for **open** processes
+-----------------------------------------------------
+
+It's easy to get frustrated with existing development tools. Too often they are overbearing, complex, and make assumptions that get in your way. And even if they are open source, it's often difficult to get them to work the way you need them too.
+
+Which is why we created Allura. It's designed to be truly **open**, in many different senses of the word.
+
+It's open in bunch of ways:
+
+* It's a combination of tools available under *Free* or *Open Source* licenses.
+* It's designed around a plugin architecture, and anybody willing to contribute a tool can play.
+* It's being hosted publicly, and is built through contributions of individuals and companies who want to promote Open Source development.
+* It's designed to provide a structure around which welcoming (open) communities can grow.
+* Its core tools are designed around inclusive development processes.
+
+We looked at existing forges, but to achieve all those goals, we decided we needed to build something new.
+
+Allura is designed to support an **ecosystem**
+----------------------------------------------
+
+Allura is at once a **set of tools** to help people collaboratively develop software, and an **open platform** on which innovative new tools be built.
+
+
+
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/getting_started/administration.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/administration.rst b/Allura/docs/getting_started/administration.rst
new file mode 100644
index 0000000..4410f55
--- /dev/null
+++ b/Allura/docs/getting_started/administration.rst
@@ -0,0 +1,115 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+**************
+Administration
+**************
+
+Commands, Scripts, and Tasks
+----------------------------
+
+Allura has many `paster` commands and `paster` scripts that can be run from the
+server commandline to administrate Allura. There are also tasks that can be
+run through the `taskd` system. New tasks can be submitted via the web at
+/nf/admin/task_manager Some paster commands and scripts have been set up
+so that they are runnable as tasks too, giving you the convenience of starting
+them through the web and letting `taskd` execute them, rather than from a server
+shell.
+
+Commands can be discovered and run via the `paster` command when you are in the
+'Allura' directory that has your .ini file. For example::
+
+ paster help
+ ... all commands listed here ...
+
+ paster create-neighborhood --help
+ ... specific command help ...
+
+ paster create-neighborhood development.ini myneighborhood myuser ...
+
+
+Scripts are in the `scripts/` directory and run via `paster script`. An extra
+`--` is required to separate script arguments from paster arguments. Example::
+
+ paster script development.ini ../scripts/create-allura-sitemap.py -- --help
+ ... help output ...
+
+ paster script development.ini ../scripts/create-allura-sitemap.py -- -u 100
+
+TODO: explain important scripts, commands
+
+Tasks can be run via the web interface at /nf/admin/task_manager You must know
+the full task name, e.g. `allura.tasks.admin_tasks.install_app` You can
+optionally provide a username and project and app which will get set on the
+current context (`c`). You should specify what args and kwargs will be passed
+as parameters to the task. They are specified in JSON format on the form.
+
+See the listing of :mod:`some available tasks <allura.tasks.admin_tasks>`.
+
+TODO: explain how to run scripttasks and commandtasks
+
+
+Client Scripts
+--------------
+
+Allura includes some client scripts that use Allura APIs and do not have to be run
+from an Allura server. They do require various python packages to be installed
+and possibly a local Allura codebase set up.
+
+One such script is `wiki-copy.py` which reads the wiki pages from one Allura wiki
+instance and uploads them to another Allura wiki instance. It can be run as:
+
+.. code-block:: console
+
+ $ python scripts/wiki-copy.py --help
+
+
+Site Notifications
+------------------
+
+Allura has support for site-wide notifications that appear below the site header,
+but there is currently no UI for managing them. They can easily be inserted via
+manual mongo queries, however:
+
+.. code-block:: console
+
+ > db.site_notification.insert({
+ ... active: true,
+ ... impressions: 10,
+ ... content: 'You can now reimport exported project data.'
+ ... })
+
+This will create a notification that will be shown for 10 page views or until the
+user closes it manually. An `impressions` value of 0 will show the notification
+indefinitely (until closed). The notification content can contain HTML. Only the
+most recent notification will be shown, unless it has `active:false`, in which case
+no notification will be shown.
+
+
+Using Projects and Tools
+------------------------
+
+We currently don't have any further documentation for basic operations of managing
+users, projects, and tools on Allura. However, SourceForge has help docs that cover
+these functions https://sourceforge.net/p/forge/documentation/Docs%20Home/ Note
+that this documentation also covers some SourceForge features that are not part of Allura.
+
+
+Public API Documentation
+------------------------
+
+Allura's web api is currently documented at https://sourceforge.net/p/forge/documentation/Allura%20API/
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/getting_started/index.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/index.rst b/Allura/docs/getting_started/index.rst
new file mode 100644
index 0000000..6f59b58
--- /dev/null
+++ b/Allura/docs/getting_started/index.rst
@@ -0,0 +1,32 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+
+***************
+Getting Started
+***************
+
+.. toctree::
+ :maxdepth: 2
+
+ about
+ installation
+ using
+ administration
+ scm_host
+
+
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/getting_started/installation.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/installation.rst b/Allura/docs/getting_started/installation.rst
new file mode 100644
index 0000000..3d3321a
--- /dev/null
+++ b/Allura/docs/getting_started/installation.rst
@@ -0,0 +1,107 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+************
+Installation
+************
+
+
+Our step-by-step setup instructions are in our INSTALL.markdown file. You can read it online at https://forge-allura.apache.org/p/allura/git/ci/master/tree/INSTALL.markdown You should be able to get Allura up and running in well under an hour by following those instructions.
+
+For a faster and easier setup, see our `Vagrant/VirtualBox installation guide <https://forge-allura.apache.org/p/allura/wiki/Install%20and%20Run%20Allura%20-%20Vagrant/>`_
+
+Configuring Optional Features
+-----------------------------
+
+The `development.ini` file has many options you can explore and configure. It is geared towards development, so you will want to review
+carefully and make changes for production use.
+
+To run SVN and Git services, see the :doc:`scm_host` page.
+
+Some features may be added as separate `Allura extensions <https://forge-allura.apache.org/p/allura/wiki/Extensions/>`_
+
+Enabling inbound email
+^^^^^^^^^^^^^^^^^^^^^^
+
+Allura can listen for email messages and update tools and artifacts. For example, every ticket has an email address, and
+emails sent to that address will be added as comments on the ticket. To set up the SMTP listener, run:
+
+.. code-block:: bash
+
+ nohup paster smtp_server development.ini > /var/log/allura/smtp.log &
+
+By default this uses port 8825. Depending on your mail routing, you may need to change that port number.
+And if the port is in use, this command will fail. You can check the log file for any errors.
+To change the port number, edit `development.ini` and change `forgemail.port` to the appropriate port number for your environment.
+
+SMTP in development
+^^^^^^^^^^^^^^^^^^^
+
+The following command can be used for quick and easy monitoring of smtp during development.
+Just be sure the port matches the `smtp_port` from your `development.ini` (8826 by default).
+
+.. code-block:: bash
+
+ python -m smtpd -n -c DebuggingServer localhost:8826
+
+This will create a new debugging server that discards messages and prints them to stdout.
+
+
+Using LDAP
+^^^^^^^^^^
+
+Allura has a pluggable authentication system, and can use an existing LDAP system. In your config
+file (e.g. :file:`development.ini`), there are several "ldap" settings to set:
+
+* Change auth.method to: :samp:`auth.method = ldap`
+* Set all the :samp:`auth.ldap.{*}` settings to match your LDAP server configuration. (:samp:`auth.ldap.schroot_name` won't be
+ used, don't worry about it.)
+* Keep :samp:`auth.ldap.autoregister = true` This means Allura will use existing users from your LDAP
+ server.
+* Set :samp:`auth.allow_user_registration = false` since your users already are present in LDAP.
+* Change user_prefs_storage.method to :samp:`user_prefs_storage.method = ldap`
+* Change :samp:`user_prefs_storage.ldap.fields.display_name` if needed (e.g. if display names are stored
+ in a different LDAP attribute).
+
+Restart Allura and you should be all set. Now users can log in with their LDAP credentials and their
+Allura records will be automatically created the first time they log in.
+
+Note: if you want users to register new accounts into your LDAP system via Allura, you should turn
+off :samp:`autoregister` and turn on :samp:`allow_user_registration`
+
+Enabling RabbitMQ
+^^^^^^^^^^^^^^^^^
+
+For faster notification of background jobs, you can use RabbitMQ. Assuming a base setup from the INSTALL, run these commands
+to install rabbitmq and set it up:
+
+.. code-block:: bash
+
+ sudo aptitude install rabbitmq-server
+ sudo rabbitmqctl add_user testuser testpw
+ sudo rabbitmqctl add_vhost testvhost
+ sudo rabbitmqctl set_permissions -p testvhost testuser "" ".*" ".*"
+ pip install amqplib==0.6.1 kombu==1.0.4
+
+Then edit Allura/development.ini and change `amqp.enabled = false` to `amqp.enabled = true` and uncomment the other `amqp` settings.
+
+If your `paster taskd` process is still running, restart it:
+
+.. code-block:: bash
+
+ pkill -f taskd
+ nohup paster taskd development.ini > /var/log/allura/taskd.log &
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/getting_started/scm_host.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/scm_host.rst b/Allura/docs/getting_started/scm_host.rst
new file mode 100644
index 0000000..0e91a15
--- /dev/null
+++ b/Allura/docs/getting_started/scm_host.rst
@@ -0,0 +1,241 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+.. _scm_hosting:
+
+**************
+SCM Host Setup
+**************
+
+
+Git and Subversion Hosting Installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Allura can manage and display Git and SVN repositories, but it doesn't
+automatically run the git and svn services for you. Here we'll describe how
+to set up standard git and svn services to work with Allura, so that you can
+checkout and commit code with those repositories. The instructions here assume
+an Ubuntu system, but should be similar on other systems.
+
+.. note::
+
+ For developing with Allura or simple testing of Allura, you do not need to run
+ these services. You can use local filesystem access to git and svn, which
+ works with no additional configuration.
+
+Git
+---
+
+We'll cover the basics to get you going. For additional options and details,
+see http://git-scm.com/docs/git-http-backend and http://git-scm.com/book/en/Git-on-the-Server
+and subsequent chapters.
+
+.. code-block:: bash
+
+ sudo chmod 775 /srv/* # make sure apache can read the repo dirs
+ sudo apt-get install apache2
+ sudo a2enmod proxy rewrite
+ sudo vi /etc/apache2/sites-available/default
+
+And add the following text within the :code:`<VirtualHost>` block:
+
+.. code-block:: apache
+
+ SetEnv GIT_PROJECT_ROOT /srv/git
+ SetEnv GIT_HTTP_EXPORT_ALL
+ ProxyPass /git/ !
+ ScriptAlias /git/ /usr/lib/git-core/git-http-backend/
+
+ # no authentication required at all - for testing purposes
+ SetEnv REMOTE_USER=git-allura
+
+Then exit vim (:kbd:`<esc> :wq`) and run:
+
+.. code-block:: shell-session
+
+ sudo service apache2 reload
+
+To test that it's working, run: :command:`git ls-remote http://localhost/git/p/test/git/`
+(if using Vagrant, you may also use :code:`localhost:8088` from your host machine).
+If there is no output, that is fine (it's an empty repo).
+
+.. warning::
+
+ This configuration has no authentication and is suitable for development only. See :ref:`below <auth_apache>` for auth config.
+
+Now you will want to change the :samp:`scm.host.{*}.git`
+settings in :file:`development.ini`, so that the proper commands are shown to your visitors
+when they browse the code repo web pages. The exact values to use will depend on the
+hostnames and port numbers you are using.
+
+Read-only `git://`
+^^^^^^^^^^^^^^^^^^
+If you want to run a separate readonly git service, using the git protocol instead of http,
+run: :program:`git daemon --reuseaddr --export-all --base-path=/srv/git /srv/git` It can
+be accessed at :code:`git://localhost/p/test/git`
+
+
+Subversion
+----------
+
+These instructions will cover the recommended easiest way to run Subversion with Allura.
+For an overview of other options, see http://svnbook.red-bean.com/en/1.8/svn.serverconfig.choosing.html
+and subsequent chapters.
+
+.. code-block:: bash
+
+ sudo chown allura:allura /srv/svn # or other user, as needed (e.g. "vagrant")
+
+ cat > /srv/svn/svnserve.conf <<EOF
+ [general]
+ realm = My Site SVN
+ # no authentication required at all - for testing purposes
+ anon-access = write
+ EOF
+
+ svnserve -d -r /srv/svn --log-file /tmp/svnserve.log --config-file /srv/svn/svnserve.conf
+
+Test by running: :command:`svn info svn://localhost/p/test/code/`. If you need to kill it,
+run :command:`killall svnserve` More info at http://svnbook.red-bean.com/en/1.8/svn.serverconfig.svnserve.html
+
+.. warning::
+
+ This configuration has no authentication and is suitable for development only.
+ (Maybe Allura could gain SASL support someday and use `svnserve with SASL <http://svnbook.red-bean.com/en/1.7/svn.serverconfig.svnserve.html#svn.serverconfig.svnserve.sasl>`_)
+
+Now you will want to change the :samp:`scm.host.{*}.svn`
+settings in :file:`development.ini`, so that the proper commands are shown to your visitors
+when they browse the code repo web pages.
+
+Alternate Setup with HTTP
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use SVN over HTTP, you will need to patch and compile an Apache module, so
+that all svn repos can be dynamically served.
+
+.. warning::
+
+ Not easy.
+
+.. code-block:: console
+
+ sudo aptitude install libapache2-svn
+
+Test accessing http://localhost/ (`localhost:8088` if using Vagrant).
+
+Now we'll configure Apache to serve a single project's repositories and make sure
+that works.
+
+.. code-block:: console
+
+ sudo vi /etc/apache2/mods-available/dav_svn.conf
+
+Uncomment and change to :code:`<Location /svn/p/test>`. Set
+:code:`SVNParentPath /srv/svn/p/test` Then run:
+
+.. code-block:: console
+
+ sudo service apache2 reload
+
+Test at http://localhost/svn/p/test/code/ (`localhost:8088` if using Vagrant)
+
+That configuration works only for the repositories in a single project. You must either
+create a new configuration for each project within Allura, or compile a patch
+to make `SVNParentPath` be recursive. The patch is at http://pastie.org/8550810
+and must be applied to the source of Subversion 1.7's mod_dav_svn and then
+recompiled and installed. (See http://subversion.tigris.org/issues/show_bug.cgi?id=3588
+for the request to include this patch in Subversion itself). Once that is working,
+you can modify :file:`dav_svn.conf` to look like:
+
+.. code-block:: apache
+
+ <Location /svn>
+ DAV svn
+ SVNParentPath /srv/svn
+ ...
+
+Then Apache SVN will serve repositories for all Allura projects and subprojects.
+
+.. warning::
+
+ This configuration has no authentication and is suitable for development only. See :ref:`the next section <auth_apache>` for auth config.
+
+
+.. _auth_apache:
+
+Configuring Auth with Apache
+----------------------------
+
+This is the easiest way to integrate authentication and authorization for SCM access with Allura. It uses
+mod_python and the handler in :file:`scripts/ApacheAccessHandler.py` to query Allura directly
+for auth and permissions before allowing access to the SCM. Of course, this only works
+for SCM access over HTTP(S).
+
+First, you need to ensure that mod_python is installed:
+
+.. code-block:: console
+
+ sudo aptitude install libapache2-mod-python
+
+Then, in the VirtualHost section where you proxy SCM requests to git, SVN, or Hg, add the
+access handler, e.g.:
+
+.. code-block:: console
+
+ sudo vi /etc/apache2/sites-available/default
+
+.. code-block:: apache
+
+ <LocationMatch "^/(git|svn|hg)/">
+ AddHandler mod_python .py
+ # Change this path if needed:
+ PythonAccessHandler /home/vagrant/src/allura/scripts/ApacheAccessHandler.py
+ AuthType Basic
+ AuthName "SCM Access"
+ AuthBasicAuthoritative off
+ # Change this path if needed:
+ PythonOption ALLURA_VIRTUALENV /home/vagrant/env-allura
+ # This routes back to the allura webapp, port 8080 if running with paster server (~/start_allura)
+ # In a production environment, run allura with a real WSGI server, and
+ # change the IP address and port number as appropriate.
+ # And use https if possible, since the username and password are otherwise
+ # sent in the clear to Allura.
+ PythonOption ALLURA_AUTH_URL http://127.0.0.1:8080/auth/do_login
+ PythonOption ALLURA_PERM_URL http://127.0.0.1:8080/auth/repo_permissions
+ </LocationMatch>
+
+.. code-block:: console
+
+ sudo service apache2 reload
+
+To test that it's working, run: :command:`git ls-remote
+http://localhost/git/p/test/git/` (if using Vagrant, use :code:`localhost:8088`
+from your host machine). If there is no output, that is fine (it's an empty
+repo). If it errors, look in :file:`/var/log/apache2/error.log` for the error
+message.
+
+.. warning::
+
+ Currently, for Mercurial, the handler doesn't correctly distinguish read
+ and write requests and thus requires WRITE permission for every request.
+ See ticket #7288
+
+
+Advanced Alternative
+--------------------
+
+An advanced alternative for SCM hosting using :ref:`SSH, LDAP, and a FUSE driver <scm_hosting_ssh>` is available.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/ae5d2746/Allura/docs/getting_started/scm_host_ssh.rst
----------------------------------------------------------------------
diff --git a/Allura/docs/getting_started/scm_host_ssh.rst b/Allura/docs/getting_started/scm_host_ssh.rst
new file mode 100644
index 0000000..bba57cf
--- /dev/null
+++ b/Allura/docs/getting_started/scm_host_ssh.rst
@@ -0,0 +1,203 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+
+:orphan:
+
+.. _scm_hosting_ssh:
+
+***************
+SCM Hosting-SSH
+***************
+
+Configuring Git/SVN/Hg to use Allura auth via LDAP and ssh
+==========================================================
+
+The following instructions will use a chroot, a custom FUSE driver, and LDAP.
+Once completed, an ssh-based configuration of Git, SVN, or Hg that has repos in
+the chroot directory will authenticate the users against LDAP and authorize via an Allura API.
+Allura will be configured to authenticate against LDAP as well.
+
+.. note::
+
+ The previous git & svn configuration instructions are not ssh-based, so will not work with this configuration.
+ You'll have to reconfigure git & svn to use ssh:// instead of http or svn protocols.
+
+We assume you are using a version of Ubuntu with
+support for schroot and debootstrap. We will use a chroot jail to allow users to
+access their repositories via ssh.
+
+Install a chroot environment
+----------------------------
+
+These instructions are based on the documentation in `Debootstrap Chroot`_. and `OpenLDAPServer`_.
+
+Install debootstrap and schroot: :program:`aptitude install debootstrap schroot`
+
+Append the following text to the file :file:`/etc/schroot/schroot.conf`
+
+.. code-block:: ini
+
+ [scm]
+ description=Ubuntu Chroot for SCM Hosting
+ type=directory
+ directory=/var/chroots/scm
+ script-config=scm/config
+
+Create a directory :file:`/etc/schroot/scm` and populate it with some files:
+
+.. code-block:: console
+
+ # mkdir /etc/schroot/scm
+ # cat > /etc/schroot/scm/config <<EOF
+ FSTAB="/etc/schroot/scm/fstab"
+ COPYFILES="/etc/schroot/scm/copyfiles"
+ NSSDATABASES="/etc/schroot/scm/nssdatabases"
+ EOF
+ # cat > /etc/schroot/scm/fstab <<EOF
+ /proc /proc none rw,rbind 0 0
+ /sys /sys none rw,rbind 0 0
+ /dev /dev none rw,rbind 0 0
+ /tmp /tmp none rw,bind 0 0
+ EOF
+ # cat > /etc/schroot/scm/copyfiles <<EOF
+ /etc/resolv.conf
+ EOF
+ # cat > /etc/schroot/scm/nssdatabases <<EOF
+ services
+ protocols
+ networks
+ hosts
+ EOF
+
+Create a directory :file:`/var/chroots/scm` and create the bootstrap environment. (You may substitute a mirror from the `ubuntu mirror list`_ for archive.ubuntu.com)
+
+.. code-block:: console
+
+ $ sudo mkdir -p /var/chroots/scm
+ $ sudo debootstrap --variant=buildd --arch amd64 --components=main,universe --include=git,mercurial,subversion,openssh-server,slapd,ldap-utils,ldap-auth-client,curl maverick /var/chroots/scm http://archive.ubuntu.com/ubuntu/
+
+Test that the chroot is installed by entering it:
+
+.. code-block:: console
+
+ # schroot -c scm -u root
+ (scm) # logout
+
+Configure OpenLDAP in the Chroot
+--------------------------------
+
+Copy the ldap-setup script into the chroot environment:
+
+.. code-block:: console
+
+ $ sudo cp Allura/ldap-setup.py Allura/ldap-userconfig.py /var/chroots/scm
+ $ sudo chmod +x /var/chroots/scm/ldap-*.py
+
+Log in to the chroot environment:
+
+.. code-block:: console
+
+ # schroot -c scm -u root
+
+Run the setup script, following the prompts:
+
+.. code-block:: console
+
+ (scm) # python /ldap-setup.py
+
+In particular, you will need to answer the following questions (substitute your custom suffix if you are not using dc=localdomain):
+
+* Should debconf manage LDAP configuration? **yes**
+* LDAP server Uniform Resource Identifier: **ldapi:///**
+* Distinguished name of the search base: **dc=localdomain**
+* LDAP version to use: **1** (version 3)
+* Make local root Database admin: **yes**
+* Does the LDAP database require login? **no**
+* LDAP account for root: **cn=admin,dc=localdomain**
+* LDAP root account password: *empty*
+* Local crypt to use when changing passwords: **2** (crypt)
+* PAM profiles to enable: **2**
+
+Update the chroot ssh configuration
+-----------------------------------
+
+Update the file :file:`/var/chroot/scm/etc/ssh/sshd_config`, changing the port directive:
+
+.. code-block:: guess
+
+ # Port 22
+ Port 8022
+
+Setup the Custom FUSE Driver
+----------------------------
+
+Copy the accessfs script into the chroot environment:
+
+.. code-block:: console
+
+ $ sudo cp fuse/accessfs.py /var/chroots/scm
+
+Configure allura to point to the chrooted scm environment:
+
+.. code-block:: console
+
+ $ sudo ln -s /var/chroots/scm /srv/git
+ $ sudo ln -s /var/chroots/scm /srv/hg
+ $ sudo ln -s /var/chroots/scm /srv/svn
+
+Log in to the chroot environment & install packages:
+
+.. code-block:: console
+
+ # schroot -c scm -u root
+ (scm) # apt-get install python-fuse
+
+Create the SCM directories:
+
+.. code-block:: console
+
+ (scm) # mkdir /scm /scm-repo
+
+Mount the FUSE filesystem:
+
+.. code-block:: console
+
+ (scm) # python /accessfs.py /scm-repo -o allow_other -s -o root=/scm
+
+Start the SSH daemon:
+
+.. code-block:: console
+
+ (scm) # /etc/init.d/ssh start
+
+Configure Allura to Use the LDAP Server
+---------------------------------------
+
+Set the following values in your .ini file:
+
+.. code-block:: ini
+
+ auth.method = ldap
+
+ auth.ldap.server = ldap://localhost
+ auth.ldap.suffix = ou=people,dc=localdomain
+ auth.ldap.admin_dn = cn=admin,dc=localdomain
+ auth.ldap.admin_password = secret
+
+.. _Debootstrap Chroot: https://help.ubuntu.com/community/DebootstrapChroot
+.. _OpenLDAPServer: https://help.ubuntu.com/10.10/serverguide/C/openldap-server.html
+.. _ubuntu mirror list: https://launchpad.net/ubuntu/+archivemirrors