.. -*- coding: utf-8 -*- .. :Progetto: Metapensiero -- Buildout .. :Creato: sab 18 dic 2010 11:28:06 CET .. :Autore: Lele Gaifax .. :Licenza: GNU General Public License version 3 or later .. ======================= Metapensiero buildout ======================= This repository contains the buildout_ used to setup our public development site, currently composed by a Plone_ instance__, various Trac_ instances__, a set of Darcs_ repositories__ and a SoL_ demo__. .. _buildout: http://www.buildout.org/ .. _plone: http://plone.org/ __ http://metapensiero.it/ .. _trac: http://trac.edgewall.org/ __ http://progetti.metapensiero.it/ .. _darcs: http://darcs.net/ __ http://darcs.metapensiero.it/ .. _sol: http://progetti.metapensiero.it/sol/ __ http://sol.arstecnica.it/ Pre-requirements ================ Installing the complete stack requires some already installed packages, mainly: * Python 2.6 * Development libraries - python2.6-dev - libjpeg8-dev - libyaml-dev * Development tools - gcc - make Installation ============ To bootstrap the environment, issue the following command :: $ python bootstrap.py --distribute This in particular creates ``bin/buildout``, the tool that effectively will download and install a lot of other tools (such as nginx_ and uwsgi_) and Python packages. This step must be done just once, right after the checkout of this repository. .. _nginx: http://nginx.org/ .. _uwsgi: http://projects.unbit.it/uwsgi/ Buildout execution ------------------ The following command must be executed whenever you change the configuration (i.e. any of those `*.cfg`` files in the buildout directory, or the skeletons under ``templates/``):: $ bin/buildout The first time this will take some time, as it fetches from the internet hundreds of packages. It will also compile a few modules written in ``C``, and that takes time too. Also, whenever it creates a new Trac instance, it will possibly clone the configured repositories and `synchronize` the Trac instance. In two words, be patience! Activation ---------- Once ``buildout`` is done the environment is ready. You can activate it with :: $ bin/service start that basically just starts the supervisor_, a process that in turn will launch two uwsgi_ servers, one for the SoL_ instance and one for the Trac ones, the Plone instance and the nginx_ frontend. After that, if everything's right you should be able to visit your shiny new site with :: $ python -m webbrowser http://localhost:8080/ .. _supervisor: http://supervisord.org/ Production ---------- To deploy the system in production, you probably should execute the following commands, as ``root``: 1. ``ln -s $(pwd)/bin/service /etc/init.d/your-site-name`` 2. ``update-rc.d your-site-name defaults`` 3. ``ln -s $(pwd)/etc/logrotate.conf /etc/logrotate.d/your-site-name`` SoL instance ------------ Due to a bug I wasn't able to find a reasonable workaround, currently the buildout does not `prepare` the required SoL database and this must be done manually, with:: $ bin/paster setup-app etc/sol.ini You may also want to load the initial data, with:: $ bin/paster --plugin SoL restore etc/sol.ini http://some-existing-sol-instance/ Darcs repositories ------------------ The repositories are already exposed via http by the nginx_ frontend, obviously read-only. To be able to push changes from the outside, you should create a ``darcs`` user with an home directory set to the root of the repositories (``var/darcs``) and using the patched__ (with Darcs_ support, based on an `old patch`__) rssh_ installed as ``bin/rssh``, for example:: darcs:x:1000:1000:,,,:/srv/var/darcs:/srv/bin/rssh __ rssh-2.3.3-darcs.patch __ http://sourceforge.net/tracker/index.php?func=detail&aid=1351939&group_id=65349&atid=510643 .. _rssh: http://sourceforge.net/projects/rssh/ Also, you need to enable the ``allowdarcs`` in the ``etc/rssh.conf`` file: with recent darcses it's enough, as ``scp`` isn't used anymore thanks to the new ``transfer-mode`` subcommand. .. note:: The configuration files get **rewritten** each time your execute ``bin/buildout``, so be sure to re-enable that option... With this inplace, the ``darcs`` user will be able to execute **only** the ``darcs`` executable found by rssh configure, and **only** the three subcomands ``apply``, ``initialize`` and ``transfer-mode``, and **only** on *relative* paths, thus effectively restricting the allowed operations to its home directory. Now, if you haven't already got them, you'll need an ssh public key from each person that you want to give access to. They can use public keys they already have, or generate keys just for this purpose, for example with:: $ cd ~/.ssh $ ssh-keygen -t dsa -f for-darcs-identity In this case they should also put something like the following in their ``~/.ssh/config`` file to select the right identity when they comunicate with ``metapensiero.it``:: Host metapensiero.it IdentityFile ~/.ssh/for-darcs-identity You should then add each collected public key to the ``authorized_keys`` of the ``darcs`` user (i.e. ``/srv/var/darcs/.ssh/authorized_keys`` in the example above). At that point, any authorized user should be able to access any repository via ``SSH``, for example with:: $ darcs get darcs@metapensiero.it:tailor Even if users will be able to create new repositories using ``darcs put`` there is no way for them to create arbitrary subdirectories in the repositories tree; in other words, new repositories can only be created in **existing** folders (yes, even nested within another repository tree). The administrator shall eventually create new folders under the ``darcs`` home directory. One particular subtree, rooted at ``our``, isn't browsable from the web: this is where we store our `semi-public`, `restricted` stuff, for example code that is not yet ready for public consumption. A reasonable policy could create a specific folder for a given user, say ``our/johndoe`` and ``our/sarahbeltemp``, where John and Sarah keep their own branches of the same product... .. warning:: This is just a `weak trick`__ we found adeguate to our purposes: **don't** rely on it for `private` stuff that should not leak around. __ http://en.wikipedia.org/wiki/Security_through_obscurity To give access to this area, you simply hand the full URL of the repository to the people: once they know the exact location, they can extract the repository, and eventually push changes there. Proxies to other servers ------------------------ The nginx configuration automatically includes any ``*.conf`` under the ``etc/vhosts/`` subdirectory. This is meant as way to attach a proxy to another server, say a Plone instance running in its own vserver, possibly by hard-linking the appropriate configuration snippet to that location. Further customizations ====================== To adapt the buildout to your needs you probably want 1. tweak the default passwords in ``users.cfg`` .. warning:: Avoid to commit back in the master repository any sensible information! 2. replace ``metapensiero.it`` with your own domain in ``tracs.cfg`` and ``templates/nginx.conf.in`` 3. replace Trac instances with your own.