================================================
codespeak administration docs (alpha) 
================================================

.. contents::
.. sectnum::

Getting started 
================================================


.. _`#codespeak irc`: 

Joining the #codespeak channel on freenode 
-------------------------------------------- 

Admin and root users of codespeak are hanging 
around on ``#codespeak`` at irc.freenode.org - please 
drop by if you have questions or want to help 
in some area. 


Subscribing to the admin mailing list 
----------------------------------------- 

It's a good start to `subscribe to the admin list`_ in order
to see what's going on with codespeak administration. 

.. _`subscribe to the admin list`: http://codespeak.net/mailman/listinfo/admin 

Getting SUDO rights 
-------------------------

In order to get SUDO rights you must `subscribe to the admin list`_
and should also be around the `#codespeak irc`_ channel sometimes. 
You also need to have an `account on codespeak`_ already and have 
a track record in some of its hosted projects or be well known
to existing wheel users. 

Using the versioned administration tool 
-------------------------------------------

In codespeak we are using a tool called **vadm** which lets
us version-control system configuration files including 
permissions and ownership information.  

Once you have SUDO rights, you can login to codespeak.net 
as a user and perform the initilization like this:: 

     vadm init 

This will create a working-copy of the system-respository
in your $HOME/.vadm/code0.codespeak.net/code0.codespeak.net
directory.

Now (being in the wheel group which is allowed to perform 
SUDO commands) you can use commands like

    vadm status /etc

to see which files are modified.  Basically you have a lot
of the commands you have with plain svn:: 

     vadm ci /some/dir_or_file
     vadm diff /some/dir_or_file
     vadm status /some/dir_or_file 
     vadm add /some/more/file 
     vadm revert /some/more/file 
    
The only thing that is done automatically for you is 
updating from the underlying host repository.  This is 
so because the administrators are sharing the system 
files and it seems to be conceptually difficult to keep a user-specific 
view of the whole filesystem. 

vadm monitors content as well as permissions.  'vadm' uses
the `py lib`_ and it is an unreleased tool but used on a number
of servers already.  It certainly needs improvements especially
speed-wise but should otherwise work reasonably well. 

.. _`py lib`: http://codespeak.net/py


.. _`account on codespeak`: 

creating a new user 
-----------------------------

We have a script for creating users which requires
three parameters::  

    /admin/bin/cs_adduser accountname realname emailaddress 

It takes care of creating a password, adding 
appropriate groups. You still have to transmit the
password securely to the user in question - please
advise him to change the password immediately. 


Overwiev about codespeak installation and internals 
============================================================

XXX describe Gentoo setup here 

modifying admin (this!) documentation
----------------------------------------

If you want to help putting more information onto
these pages, please checkout the doc directory:: 

    svn co http://codespeak.net/svn/admin/doc admin-doc 

then 'cd' to ``admin-doc`` directory.  

Here you can edit the files in `ReST-Format`_ and issue `py.test`_ 
to check integrity and correct formatting for the documentation. 
If you issue ``py.test -R -v`` it will check remote links as well. 

If you commit changes they will become available on the web
page almost immediately. 

.. _`ReST-Format`: http://docutils.sourceforge.net/docs/rst/quickref.html
.. _`py.test`: http://codespeak.net/py/current/doc/test.html


Admin Directory Structure
------------------------- 

Here is a short description of the ``/admin`` directory hierarchy::

    /admin/bin/     contains scripts and binaries 
    /admin/lib/     contains dynamic libraries (installed from our helpers) 
    /admin/etc/     contains common etc-files such as init.d scripts 
    /admin/codespeak  contains a number of tools, usually installed to /admin 
    /admin/package  contains python packages which need to be 
                    '+ python setup.py install'ed. 


Environment 
----------- 

cmdline environment
+++++++++++++++++++

``/admin/bin`` and ``/admin/lib`` are added via 
/etc/env.d/00admin which requires a 'env-update' after
each change. 

python packages
+++++++++++++++

For deployment of system level scripts we want to make sure
that versions of the py lib and 'uconf' are reachable everywhere. 
Therefore one can do the following:: 

    cd /admin/package
    + sh install.sh 

This will install all needed packages appropriately. 

Subversion
------------

Subversion needs a number of maintenace tools and configuration:: 

    $REPO/hooks/post-commit     # contains calls to 'svn-mailer.py' 

    /admin/bin/svn-mailer.py    # script to send commit mails 
                                # (pass $REPO and $REV as
                                # cmdline arguments)
                                
    /admin/bin/commit-by-path   # script invoked from the post-commit
                                # hook in order to execute
                                # per-user post-commit actions 
                                
    /admin/bin/recoversvn       # repair/fix a broken subversion repository 
   
hotsync of svn repository 
------------------------------------

XXX backup each commit to a different host

user permissions 
---------------- 

XXX find a way to specify permissions for subtrees of a subversion
repository and generate apache-conf, password etc.pp. files. 

Misc
----------

`Quickreference to ReST`_ (the format, used to write this README.txt) 


.. _`Quickreference to ReST`: http://docutils.sourceforge.net/docs/user/rst/quickref.html