--- a
+++ b/Allura/docs/scm_host.rst
@@ -0,0 +1,138 @@
+SCM (Git, Mercurial, Subversion) Hosting Installation
+==========================================================
+
+The following instructions assume you are using a version of Ubuntu Linux with
+support for dchroot 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 schroot
+
+#. Append the following text to the file /etc/schroot/schroot.conf::
+
+ [scm]
+ description=Ubuntu Chroot for SCM Hosting
+ type=directory
+ directory=/var/chroots/scm
+ script-config=scm/config
+
+#. Create a directory /etc/schroot/scm and populate it with some files::
+
+ # 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 /var/chroots/scm and create the bootstrap environment. (You may substitute a mirror from the `ubuntu mirror list`_ for archive.ubuntu.com::
+
+ $ 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::
+
+ # schroot -c scm -u root
+ (scm) # logout
+
+Configure OpenLDAP in the Chroot
+--------------------------------------------------------------
+
+#. Copy the ldap-setup script into the chroot environment
+
+ $ 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:
+
+ # schroot -c scm -u root
+
+#. Run the setup script, following the prompts.
+
+ (scm) # python /ldap-setup.py
+
+In particular, you will need to anwer 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 /var/chroot/scm/etc/ssh/sshd_config, changing the port directive::
+
+ # Port 22
+ Port 8022
+
+Setup the Custom FUSE Driver
+-------------------------------------
+
+#. Copy the accessfs script into the chroot environment
+
+ $ sudo cp fuse/accessfs.py /var/chroots/scm
+
+#. Configure allura to point to the chrooted scm environment
+
+ $ sudo ln -s /var/chroots/scm /git
+ $ sudo ln -s /var/chroots/scm /hg
+ $ sudo ln -s /var/chroots/scm /svn
+
+#. Log in to the chroot environment & install packages:
+
+ # schroot -c scm -u root
+ (scm) # apt-get install python-fuse
+
+#. Create the SCM directories
+
+ (scm) # mkdir /scm /scm-repo
+
+#. Mount the FUSE filesystem
+
+ (scm) # python /accessfs.py /scm-repo -o allow_other -s -o root=/scm
+
+#. Start the SSH daemon
+
+ (scm) # /etc/init.d/ssh start
+
+Configure Allura to Use the LDAP Server
+------------------------------------------------
+
+Set the following values in your .ini file:
+
+ 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