NAME

repocafe - self-service for svn hosting


USAGE

Repocafe helps admins and users to manage subversion repositories.

Central to a repocafe installation is the config file. It is used by the web application, and all setup- and support scripts.

Creating a config file is the biggest part of setting up a repocafe.


CONFIG FILE

location

The default locations of the config file are :

syntax

A config file looks like this :

  +--------------------------------------------------
  |# lines that start with '#' are comment
  |# blank lines are ignored too
  |# tabs are replaced by a space
  |
  |# the config entries are 'key' and 'value' pairs
  |# a 'key' begins in column 1
  |# the 'value' is the rest of the line
  |somekey  part1 part2 part3 ...
  |otherkey part1 part2 part3 ...
  |
  |# keyword EMPTY represents the empty string ;
  |# in the next line some_key's part2 is set to ''
  |somekey part1 EMPTY part3 ...
  |
  |# indented lines are glued
  |# the next three lines mean 'somekey part1 part2 part3'
  |somekey part1
  |  part2
  |  part3
  |
  |# lines starting with a '+' are concatenated
  |# the next three lines mean 'somekey part1part2part3'
  |somekey part1
  |+ part2
  |+ part3
  |
  |# lines starting with a '.' are glued too
  |# don't use a '.' on a line by itself
  |# 'somekey' gets the value "part1\n part2\n part3"
  |somekey part1
  |. part2
  |. part3
  +--------------------------------------------------

In some places in the config (so indicated below) you can glue a ``string with spaces'' into one part by replacing spaces with underscores as in string_with_spaces.

config file : required entries

dir_admin path

Specify the full pathname of the admin tree.

  dir_admin /path/to/admin-tree
dir_www path

Specify the full pathname of the www tree.

  dir_www /path/to/www-tree
dir_data path

Specify the full pathname of the directory where the data lives.

  dir_data /path/to/data-tree

The data directory is created by setup-data in the setup phase. It contains subdirectories admin, archive, logs and repos.

organisation html

Specify the name of your organisation ; this will be embedded in the user documention, so an url is fine.

  organisation <a href="http://www.my.org">my organisation</a>
db_host host

Specify the hostname of your database server

  db_host pghost.some.name.org
db_name name

Specify the name of the database where the repocafe tables live.

See db_pref below.

db_user user

Specify the username for the database connections in applications.

db_pswd password

Specify the password for the database connections in applications.

admin_user name

Specify the uid (name or number) of the user who owns the files in the admin tree and the www tree. This information is used only in the setup-scripts.

admin_group name

Specify the gid (name or number) of the admin_user. This information is used only in the setup-scripts.

www_user name

Specify the uid (name or number) of the apache httpd run-user (APACHE_RUN_USER). All files created by the httpd (including the repositories, logs etc) will be owned by this uid. This information is used only in the setup-scripts.

www_group name

Specify the gid (name or number) of the www_user (APACHE_RUN_GROUP). This information is used only in the setup-scripts.

www_server name

Specify the name of your web server

  www_server repocafe.science.uu.nl
www_secret string

Specify a long, secret (random) string ; this secret is used in the web applications to checksum the contents of sessions, protect plots from prying eyes etc.

  www_secret jlsadywr4n8sdydf8wery

Your secret should be random, and at least 16 characters long.

www_contact string

Specify an email address, so users can contact the svn-admins.

  www_contact svn-admins@my.org

This address is also used in (the default for) the From:-line of mail sent to guests ; see mail_from_admin.

clas class ldap ldap-tag pattern [description]
clas guests table repo_guests login passwd name [description]

Specify one or more user classes. When a user attempts to login, the clas-lines are tried in turn to verify the user's username and password. The line that succeeds, determines the logged-in user's class.

The description should describe the user class (staff, students, sales, marketing). Write blanks as underscores to make it a single string. The descriptions are shown on the login page, and should explain which users should use what username/passwd. The default for description is the configured class.

For an ldap user class, the ldap server, identified by ldap-tag, is queried anonymously. If/when a DN is returned, it is matched against pattern. If it matches, an authenticated bind is done. If it succeeds, the user is authenticated. Use optional config entry ldap to configure ldap-servers.

For the guests user class, a database table lookup is done. If it succeeds and the password matches, the user's class is 'guests'. If you want guests, copy this line into the config:

  clas guests table repo_guests login passwd name

The extra parameters (table, repo_guests, login, passwd, name) are there for possible future enhancements.

A simple setup would be :

  ldap myldap ldap.your.org ou=people,dc=my.org,dc=nl usual
  clas guests table repo_guests login passwd name
  clas user   ldap myldap ,ou=people my.org_users

You have guest accounts, and one class of ldap users. The login page says :

    guests       : use the login/password we sent you
    my.org users : use your usual login/password

A more complicated example :

  ldap sci ldap.science.uu.nl dc=science,dc=uu,dc=nl solis-id/password
  ldap art ldap.arts.uu.nl    dc=arts,dc=uu,dc=nl    arts.uu.nl_id
  clas guests   table repo_guests login passwd name
  clas sci      ldap sci ou=staff,ou=users     science_staff
  clas edu      ldap sci ou=students,ou=users  science_students
  clas staff    ldap art ou=people,ou=staff    arts_staff
  clas students ldap art ou=people,ou=students arts_students

Here we define two ldap servers, one for 'science' (with usernames known as solis id's) and one for 'arts' (with arts.uu.nl id's).

We have five user classes: guests, science staff and students, arts staff and students.

tree path prefix [user-classes]

Specify one or more tree-lines. It describes how actual repository names are structured. Field user-classes is a (possibly empty) comma-separated list of user classes (eg staff,students).

When a user creates a repository, he/she supplies an alpha-numeric name for the repository. Optionally, this name is prefixed with a tag that depends on the user's class and/or username. For instance, if you want staff repository names to be prefixed with 'stf', and student's repository names with 'edu', you specify

  tree stf %p staff
  tree edu %p student

If you want student's repository names prefixed with 'edu.loginname', you specify

  tree edu %p.%o student

Admins can create repositories in all trees ; if no user-classes are specified in a tree-line, users are told repositories in that tree can be created on request. You configure :

  tree <path> <prefix> EMPTY

For a simple, flat namespace, specify

  tree EMPTY EMPTY clas1,clas2,clas3

where keyword EMPTY represents the empty string and clas1,clas2,clas3 sums up the user classes that may create repositories. The name of a repository will be the name supplied by the owner/creator of the repository.

In general, each tree-line specifies which user classes can create repositories prefixed with the given path. The actual repository names are generated by substituting, in the given prefix, the given path for '%p' and the username of the creator for '%o'.

Caveat: Once you configure a certain tree layout, you can't change or remove a tree-line, if/when repositories in that tree have been created. The actual file path of a new repository isn't saved in the database after creation. Instead, the pathname is recomputed each time when needed, based on tree, owner and name and the config file. So, if/when the (user or tree) config changes, we can't compute the proper repo's pathname from the info in the database. Hm, a quick fix seems obvious. However, the best solution would be to put user/tree stuff in the database and under application control, so a change in 'config' could result in a proper 'renaming' of repo's.

config file : optional entries

create_guests clas1 clas2 ...

Optionally specify the classes of users that may create guests.

  create_guests staff

If only admins may create guests, don't specify create_guests or configure

  create_guests EMPTY
no_viewvc

If you don't have package viewvc installed (yet), configure

  no_viewvc

to get rid of the (non-working) viewvc-urls in the web pages.

no_groups

If you don't want your repocafe to have groups, configure

  no_groups
motd html

Optionally specify a message-of-the-day which will be displayed prominently on every page.

ldap tag ldap-host base [description]

Optionally specify one or more ldap-hosts that can authenticate users. When a user attempts to login, the ldap-hosts are queried, using base base.

The description should be name for the username/password verified by the ldap (school id, unix/linux, usual). The descriptions are shown on the login page, and should explain which users should use what username/passwd. Write blanks as underscores to make it a single string.

  ldap cs ldap.cs.uu.nl dc=cs,dc=uu,dc=nl cs.uu.nl_user_id

The default for description is the configured tag.

See optional configuration entries bind and attr for more configuration options.

bind ldap-tag binddn bindpw

Optionally specify a dn and password for the indicated ldap-server ; useful only if the ldap-server does not allow anonymous binds.

attr ldap-tag login full-name email

Optionally specify the attribute-names for the indicated ldap-server.

The default is

  attr <ldap-tag> uid cn mail

Some ldap-servers use this set of attribute-names :

  attr <ldap-tag> cn displayName mail
top_head html
aux_head html

Optionally specify some html to be included at the beginning (end) of the HEAD-section of every page.

top_body html
aux_body html

Optionally specify some html to be included at the beginning (end) of the BODY-section of every page.

top_rules_usage html

Optionally specify one or more LI items to be included in the user documentation page, as the first bullets under rules - usage.

  top_rules_usage <LI>never, never, ....
    <LI>always follow instructions of ....
aux_rules_usage html

Optionally specify one or more LI items to be included in the user documentation page, as the last bullets under rules - usage.

  aux_rules_usage <P>
    <LI>finally, remember that ...
top_statistics html

Optionally specify one or more LI items to be included in the user documentation page, as the first bullets under statistics.

aux_statistics html

Optionally specify one or more LI items to be included in the user documentation page, as the last bullets under statistics.

db_pref prefix

Optionally specify a prefix for the names of all database tables. The default is EMPTY ('') ; a prefix must be all lowercase.

db_owner user

Optionally specify a the owner of the database. This user must be allowed to create/drop tables etc. it is used to connect to the database in the setup-db and upd-admins scripts script. The default is EMPTY ('').

db_opswd password

Optionally specify the database password of the database owner ; it is used to connect to the database in the setup-db and upd-admins scripts. The default is EMPTY ('').

mail_from_admin

Optionally specify the From: address used in mail to guests ; by default, the configured www_contact mail address is used.

mail_from_noreply

Optionally specify the From: address used in commit emails ; by default, svn-no-reply@www_server is used ; where www_server is the configured www server hostname.

www_scheme http | https

Optionally specify the scheme for the www_server ; the default is

  www_scheme https
file_access filename

Optionally specify the name of the svn accessfile. The default is 'svnaccessfile'.

file_guests filename

Optionally specify the name of the DB file where the apache server looks up the guests' credentials. The default is 'guestusers'.

file_log filename

Optionally specify the name of the file where logins/outs etc are logged. The default is repocafe_log.

cmd_commit_email command

This option now obsolete.

cmd_svnadmin path

Optionally specify the full pathname of the svnadmin command. The default is /usr/bin/svnadmin.

cmd_svnlook path

Optionally specify the full pathname of the svnlook command. The default is /usr/bin/svnlook.

cmd_perl path

Optionally specify the full pathname of the perl command. The default is /usr/bin/perl.


SUPPORT SCRIPTS

The setup support scripts are documented in section INSTALLATION.

maintenance

system

The scripts in this section are called by the php programs. Normally, they are not used by repocafe admins.

mail-watchers

After a commit, program mail-watchers notifies (by mail) the repository's watchers. It inspects the diff, which contains various parts. A user is notified if he/she is a watcher of any part. The notification mail contains only the relevant parts of the diff.

  Usage: mail-watchers [-v] [-q] [-d] path-to-repo rev repo_id
  option v : be verbose ; dry-run
  option q : be quiet
  option d : show debug info
  ----------------------------------------
  - mail-watchers - send commit-mail to watchers.
  - mail-watchers is called from 'REPO/hooks/post-commit' as
      mail-watchers REPO REVISION REPO_ID
  - It computes the watchers and uses SVN::Notify to notify each watcher ;
    mail-watchers picks the relevant parts from the "svn-diff".
  - Normally mail-watchers is not used by admins.
  ----------------------------------------
mk_guest_list

Program mk_guest_list creates the DB file, used by the httpd to authenticate guests.

  Usage: mk_guest_list [-v] [-q] [-d] [-c conf] out
  option v : be verbose
  option q : be quiet
  option d : show debug info
  option c : use config <conf>
  ----------------------------------------
  - mk_guest_list - create the login:password file for guests.
  - Program mk_guest_list is called by the php programs when a guest is added/deleted,
    or when a guest changes his/her password.
  - Specifically it creates:
    out.db : a DB_file with (user -> password) pairs, used by httpd ;
    out.txt : for your information, as text, the same pairs.
  - Normally, mk_guest_list is not used by repocafe admins.
  ----------------------------------------
new-post-commit

Program new-post-commit creates post-commit hooks.

  Usage: new-commit-hook [-v] [-q] [-d] [-f] [-c conf] [-pre] [-post] [-a | repo_id]
  option v : be verbose
  option q : be quiet
  option d : show debug info
  option f : action ; otherwise dry-run
  option c : use config file <conf>
  option a : install new commit hooks for all repo's
  option pre  : only install pre-commit hooks
  option post : only install post-commit hooks
  argument repo_id : install commit hooks for repo with id <repo_id>
  ----------------------------------------
  - new-commit-hook - create repocafe commit hooks.
  - new-commit-hook creates commit-hooks for one specified repo, or all repo's (-a) ; 
  - by default, both 'pre-commit' and 'post-commit' hooks are installed,
    from templates in 'lib/'.
  - It is called by the web application when a new repository is created.
  - Normally, new-commit-hook is not used by repocafe admins.
  ----------------------------------------


INSTALLATION

requirements, pre-setup considerations

download the software

Checkout the software ; the latest release :

  checkout https://svn.science.uu.nl/repos/project.repocafe.dev/release

or the development version (recommended) :

  checkout https://svn.science.uu.nl/repos/project.repocafe.dev/trunk

The development version (trunk) is stable and used in production by the authors.

The distro has two parts : the admin tree and the www tree. The admin tree is used for setup and maintenance ; the www tree will be your apache's DOCUMENTROOT.

Later, you can move each tree to a new location ; if you do, remember to fix the config file and www/local.ppp (see below).

setup

finish

The repocafe setup is now almost complete. A few more details remain :


ADMINISTRATION

After setting up a repocafe, there is not a lot to do for the admins. Here are a few points an admin should know :


WISHLIST

Here are a few things we would like to add to Repocafe :


AUTHOR

© 2010 - 2013 Koos van den Hout - Henk P. Penning
ICT-β, Faculty of Science, Utrecht University
repocafe version 0.13.3 - Thu Dec 19 14:50:54 2013 - revision 240


Valid XHTML 1.0 Strict   Valid CSS!