REPOCAFE(1)           User Contributed Perl Documentation          REPOCAFE(1)


NNAAMMEE
       repocafe - self-service for svn hosting

UUSSAAGGEE
       Repocafe helps admins and users to manage subversion repositories.

       ·   Admins can easily set up svn hosting.

       ·   Users can create repositories and manage access rights, using a web
           application.

       ·   Authentication is ldap based, but guest accounts can be created as
           well.

       Central to a repocafe installation is the _c_o_n_f_i_g _f_i_l_e.  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.

CCOONNFFIIGG FFIILLEE
       llooccaattiioonn

       The default locations of the config file are :

       * ..//rreeppooccaaffee..ccoonnff
       * $$HHOOMMEE//..rreeppooccaaffee..ccoonnff
       * //eettcc//rreeppooccaaffee..ccoonnff

       ssyynnttaaxx

       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 _p_a_r_t by replacing spaces with underscores
       as in "string_with_spaces".

       ccoonnffiigg ffiillee :: rreeqquuiirreedd eennttrriieess


       dir_admin _p_a_t_h
           Specify the full pathname of the "admin" tree.

             dir_admin /path/to/admin-tree

       dir_www _p_a_t_h
           Specify the full pathname of the "www" tree.

             dir_www /path/to/www-tree

       dir_data _p_a_t_h
           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 _h_t_m_l
           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 _h_o_s_t
           Specify the hostname of your database server

             db_host pghost.some.name.org

       db_name _n_a_m_e
           Specify the name of the database where the repocafe tables live.

           See _d_b___p_r_e_f below.

       db_user _u_s_e_r
           Specify the username for the database connections in applications.

       db_pswd _p_a_s_s_w_o_r_d
           Specify the password for the database connections in applications.

       admin_user _n_a_m_e
           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 _n_a_m_e
           Specify the gid (name or number) of the _a_d_m_i_n___u_s_e_r.  This informa-
           tion is used only in the setup-scripts.

       www_user _n_a_m_e
           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 informa-
           tion is used only in the setup-scripts.

       www_group _n_a_m_e
           Specify the gid (name or number) of the _w_w_w___u_s_e_r
           (APACHE_RUN_GROUP).  This information is used only in the
           setup-scripts.

       www_server _n_a_m_e
           Specify the name of your web server

             www_server repocafe.science.uu.nl

       www_secret _s_t_r_i_n_g
           Specify a long, _s_e_c_r_e_t (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 _s_t_r_i_n_g
           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 _c_l_a_s_s ldap _l_d_a_p_-_t_a_g _p_a_t_t_e_r_n [_d_e_s_c_r_i_p_t_i_o_n]
       clas guests table repo_guests login passwd name [_d_e_s_c_r_i_p_t_i_o_n]
           Specify one or more _u_s_e_r _c_l_a_s_s_e_s.  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
           _c_l_a_s_s.

           The _d_e_s_c_r_i_p_t_i_o_n 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 _d_e_s_c_r_i_p_t_i_o_n is the configured _c_l_a_s_s.

           For an _l_d_a_p _u_s_e_r _c_l_a_s_s, the ldap server, identified by _l_d_a_p_-_t_a_g, is
           queried anonymously. If/when a DN is returned, it is matched
           against _p_a_t_t_e_r_n. If it matches, an authenticated bind is done.  If
           it succeeds, the user is authenticated.

           See also optional config entry _l_d_a_p.


           For the _g_u_e_s_t_s _u_s_e_r _c_l_a_s_s, 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 _s_o_l_i_s _i_d_’_s) and one for ’arts’ (with _a_r_t_s_._u_u_._n_l _i_d_’_s).

           We have five user classes: _g_u_e_s_t_s, _s_c_i_e_n_c_e staff and students, _a_r_t_s
           staff and students.

       tree _p_a_t_h _p_r_e_f_i_x [_u_s_e_r_-_c_l_a_s_s_e_s]
           Specify one or more _t_r_e_e-lines. It describes how actual repository
           names are structured. Field _u_s_e_r_-_c_l_a_s_s_e_s 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
           _n_a_m_e for the repository. Optionally, this _n_a_m_e 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._l_o_g_i_n_-
           _n_a_m_e’, you specify

             tree edu %p.%o student

           Admins can create repositories in all trees ; if no _u_s_e_r_-_c_l_a_s_s_e_s
           are specified in a tree-line, users are told repositories in that
           tree can be created _o_n _r_e_q_u_e_s_t. You configure :

             tree <path> <prefix> EMPTY

           For a simple, _f_l_a_t namespace, specify

             tree EMPTY EMPTY clas1,clas2,clas3

           where keyword  "EMPTY" represents the empty string and
           _c_l_a_s_1_,_c_l_a_s_2_,_c_l_a_s_3 sums up the user classes that may create reposi-
           tories.  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 _p_a_t_h. The actual repository
           names are generated by substituting, in the given _p_r_e_f_i_x, the given
           _p_a_t_h for ’%p’ and the username of the creator for ’%o’.

           CCaavveeaatt: 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 _t_r_e_e, _o_w_n_e_r and _n_a_m_e 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 con-
           trol, so a change in ’config’ could result in a proper ’renaming’
           of repo’s.

       ccoonnffiigg ffiillee :: ooppttiioonnaall eennttrriieess


       create_guests _c_l_a_s_1 _c_l_a_s_2 ...
           Optionally specify the classes of users that may create _g_u_e_s_t_s.

             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 _v_i_e_w_v_c 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 _g_r_o_u_p_s, configure

             no_groups

       motd _h_t_m_l
           Optionally specify a _m_e_s_s_a_g_e_-_o_f_-_t_h_e_-_d_a_y which will be displayed
           prominently on every page.

       ldap _t_a_g _l_d_a_p_-_h_o_s_t _b_a_s_e [_d_e_s_c_r_i_p_t_i_o_n]
           Optionally specify one or more _l_d_a_p_-_h_o_s_ts that can authenticate
           users.  When a user attempts to login, the _l_d_a_p_-_h_o_s_ts are queried,
           using base _b_a_s_e.

           The _d_e_s_c_r_i_p_t_i_o_n should be name for the username/password verified
           by the ldap (_s_c_h_o_o_l _i_d, _u_n_i_x_/_l_i_n_u_x, _u_s_u_a_l).  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 _d_e_s_c_r_i_p_t_i_o_n is the configured _t_a_g.

           See optional configuration entries "bind" and "attr" for more con-
           figuration options.

       bind _l_d_a_p_-_t_a_g _b_i_n_d_d_n _b_i_n_d_p_w
           Optionally specify a _d_n and _p_a_s_s_w_o_r_d for the indicated ldap-server
           ; useful only if the ldap-server does not allow anonymous binds.

       attr _l_d_a_p_-_t_a_g _l_o_g_i_n _f_u_l_l_-_n_a_m_e _e_m_a_i_l
           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 _h_t_m_l
       aux_head _h_t_m_l
           Optionally specify some html to be included at the beginning (end)
           of the "HEAD"-section of every page.

       top_body _h_t_m_l
       aux_body _h_t_m_l
           Optionally specify some html to be included at the beginning (end)
           of the "BODY"-section of every page.

       top_rules_usage _h_t_m_l
           Optionally specify one or more _L_I items to be included in the user
           documentation page, as the first bullets under _r_u_l_e_s _- _u_s_a_g_e.

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

       aux_rules_usage _h_t_m_l
           Optionally specify one or more _L_I items to be included in the user
           documentation page, as the last bullets under _r_u_l_e_s _- _u_s_a_g_e.

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

       top_statistics _h_t_m_l
           Optionally specify one or more _L_I items to be included in the user
           documentation page, as the first bullets under _s_t_a_t_i_s_t_i_c_s.

       aux_statistics _h_t_m_l
           Optionally specify one or more _L_I items to be included in the user
           documentation page, as the last bullets under _s_t_a_t_i_s_t_i_c_s.

       db_pref _p_r_e_f_i_x
           Optionally specify a _p_r_e_f_i_x for the names of all database tables.
           The default is EMPTY (’’) ; a prefix must be all lowercase.

       db_owner _u_s_e_r
           Optionally specify a the _o_w_n_e_r 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 _p_a_s_s_w_o_r_d
           Optionally specify the database _p_a_s_s_w_o_r_d of the database _o_w_n_e_r ; 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 _c_o_m_m_i_t emails ; by
           default, "svn-no-reply@"_w_w_w___s_e_r_v_e_r is used ; where "www_server" is
           the configured www server hostname.

       www_scheme _h_t_t_p ││ _h_t_t_p_s
           Optionally specify the _s_c_h_e_m_e for the _w_w_w___s_e_r_v_e_r ; the default is

             www_scheme https

       file_access _f_i_l_e_n_a_m_e
           Optionally specify the name of the svn accessfile.  The default is
           ’svnaccessfile’.

       file_guests _f_i_l_e_n_a_m_e
           Optionally specify the name of the DB file where the apache server
           looks up the guests’ credentials. The default is ’guestusers’.

       file_log _f_i_l_e_n_a_m_e
           Optionally specify the name of the file where logins/outs etc are
           logged.  The default is "repocafe_log".

       cmd_commit_email _c_o_m_m_a_n_d
           This option now obsolete.

       cmd_svnadmin _p_a_t_h
           Optionally specify the full pathname of the ssvvnnaaddmmiinn command.  The
           default is "/usr/bin/svnadmin".

       cmd_svnlook _p_a_t_h
           Optionally specify the full pathname of the ssvvnnllooookk command.  The
           default is "/usr/bin/svnlook".

       cmd_perl _p_a_t_h
           Optionally specify the full pathname of the ppeerrll command.  The
           default is "/usr/bin/perl".

SSUUPPPPOORRTT SSCCRRIIPPTTSS
       The setup support scripts are documented in section "INSTALLATION".

       mmaaiinntteennaannccee


       * mk_stats
           Program mmkk__ssttaattss collects version and size info of each repository.
           It should be run daily by cron from the configured directory
           _d_i_r___a_d_m_i_n.

             42 05 * * * ( cd <dir_admin> ; /usr/bin/perl mk_stats -f )

           A plot is genererated by "gnuplot".

             Usage: mk_stats [-v] [-q] [-d] [-f] [-p] [-t] [-c conf]
             option v : be verbose
             option q : be quiet
             option d : show debug info
             option f : action ; otherwise dry-run
             option p : just do the plots
             option t : initialize table ’repo_tots’ ; use only for upgrades
             option c : use config file <conf>
             ----------------------------------------
             - mk_stats - collect repocafe statistics.
             - For each repo, collect version and size into table repo_stats.
             - Program mk_stats should be run daily by cron.
             - Cronjob :
                 ( cd <DIR_ADMIN> ; perl mk_stats -f )
             ----------------------------------------

       * upd-xusers
           Program uuppdd--xxuusseerrss updates table "repo_xusers" (ex-users).  It
           should be run daily by cron from the configured directory
           _d_i_r___a_d_m_i_n.

             44 05 * * * ( cd <dir_admin> ; /usr/bin/perl upd-xusers -f )

           Running it as "upd-xusers -l -v" will show a detailed list of all
           logins.

             Usage: upd-xusers [-v] [-q] [-d] [-f] [-l] [-c conf] [ login ... ]
             option v  : be verbose
             option q  : be quiet
             option d  : show debug info
             option f  : action ; otherwise dry-run
             option l  : list xusers (no updates) ;
             option c  : use config <conf>
             arguments login ... : restrict to login1, login2, ...
             ----------------------------------------
             - upd-xusers - update the repo_xusers table.
             - Table repo_xusers contains repocafe users that can’t be found
               in the configured ldap(s) or table repo_guests.
             - The repo_xusers table in only used in the statistics page.
             - Running "upd-xusers -l -v" gives a detailed listing of all logins
               found as owners, in access-rights or as group members.
             - Because running upd-xusers may take some time to complete,
               we suggest to run it daily by cron.
             - Cronjob : ( cd <DIR_ADMIN> ; /usr/bin/perl upd_xusers -f )
             ----------------------------------------

       ssyysstteemm

       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 _d_i_f_f, which contains various
           _p_a_r_t_s.  A user is notified if he/she is a watcher of any _p_a_r_t.  The
           notification mail contains only the relevant parts of the _d_i_f_f.

             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.
             ----------------------------------------

IINNSSTTAALLLLAATTIIOONN
       rreeqquuiirreemmeennttss,, pprree--sseettuupp ccoonnssiiddeerraattiioonnss


       * required : perl
           Required Perl modules : "DBI", "DBD::Pg", "Net::LDAP",
           "SVN::Notify"

       * required : a secure apache web server
           Because the application handles usernames and passwords, the web-
           server should support _h_t_t_p_s connections and have a valid certifi-
           cate.

           The statistics plots use ’jpgraph’, which is easy to install.  The
           daily plots are generated with _g_n_u_p_l_o_t.

           The software now runs on apache 2.2 with php-5 ; "mod_dav" is
           required.

       * summary for _U_b_u_n_t_u _S_e_r_v_e_r
           To dress up an Ubuntu Server (10.10), you need the following :

             sudo apt-get install apache2
             sudo apt-get install subversion
             sudo apt-get install apache2 libapache2-svn
             sudo apt-get install libapache2-mod-php5
             sudo apt-get install perl
             sudo apt-get install postgresql
             sudo apt-get install gnuplot-nox
             sudo apt-get install libdbi-perl
             sudo apt-get install libdbd-pg-perl
             sudo apt-get install libnet-ldap-perl
             sudo apt-get install php5-ldap
             sudo apt-get install php5-pgsql
             sudo apt-get install libio-socket-ssl-perl
             sudo apt-get install viewvc
             sudo a2enmod authn_alias
             sudo a2enmod authn_dbm
             sudo a2enmod rewrite
             sudo a2enmod ssl
             sudo a2enmod ldap
             sudo a2enmod authnz_ldap

           Edit /etc/viewvc/viewvc.conf :

             root_parents = /data/svn/repos : svn
             docroot = /viewvc-doc

           JPGraph: dowload and install latest version from jpgraph website,
           because the packages distributed in Ubuntu are old (version 1.5) ;
           possibly due to the license of jpgraph (commercial, but free for
           opensource and non-profit use).

       * required : a postgresql database
           Repocafe needs some postgresql database tables to store informa-
           tion.  To set up the database, talk to your database administrator
           (DBA).

           First determine a database _u_s_e_r (username, password) that can
           _s_e_l_e_c_t_/_d_e_l_e_t_e_/_u_p_d_a_t_e the tables ; you configure :

             db_user ...
             db_pswd ...

           How you obtain a new, empty database depends on your DBA.

           IIff yyoouurr DDBBAA lleettss yyoouu oowwnn aa ddaattaabbaassee, determine a database _o_w_n_e_r
           (username, password).

           Ask your DBA to create a database "repocafe" where _o_w_n_e_r has been
           granted all priviliges :

             CREATE DATABASE repocafe WITH OWNER <owner>

           or

             CREATE DATABASE repocafe
             GRANT ALL ON DATABASE repocafe TO <owner>

           You configure the database owner’s username and password :

             db_owner ....
             db_opswd ....

           IIff yyoouurr DDBBAA ccaann’’tt lleett yyoouu oowwnn aa ddaattaabbaassee, she has to create the
           database tables for you. There are two cases :

           1 the DBA wants to create the tables in a new database
               You configure :

                 db_pref  EMPTY
                 db_owner EMPTY
                 db_opswd EMPTY

           2 the DBA wants to create the tables in an existing database
               Now your DBA may want to prefix the table names with a common
               prefix _m_y___p_r_e_f_i_x. You configure :

                 db_pref  <my-prefix>
                 db_owner EMPTY
                 db_opswd EMPTY

           When you have finished creating your config, send your DBA the out-
           put of

             setup-db -sql

           The DBA can create the tables for you, and your database setup is
           complete.

       * consideration : structure repocafe’s repository names
           If you expect that your users will create many (hundreds of) repos-
           itories, and you have two or more identifiable user groups, you may
           want to divide up the repository name space, so the repository
           overviews will look more _o_r_g_a_n_i_s_e_d. For details, see the config
           entries for _u_s_e_r and _t_r_e_e. Please note that if you decide not to
           structure your name space, adding (or changing) structure later,
           will require a lot of hand-work.

       ddoowwnnllooaadd tthhee ssooffttwwaarree

       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 _d_e_v_e_l_o_p_m_e_n_t _v_e_r_s_i_o_n ("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).

       sseettuupp


       * documentation
           The documentation is in de "admin/doc" directory :

           - "repocafe.html"
               a html page

           - "repocafe.1"
               a man(1) source

           - "repocafe.txt"
               a formatted man page

           All three pages contain the same information.

       * the config file
           In the "admin" tree, create the config file "repocafe.conf".  Here
           is a start :

             organisation <a href="http://www.my-org.org/">
             . Name of My Organisation</a>

             dir_admin /path/to/admin/tree
             dir_data  /path/to/data/tree
             dir_www   /path/to/www/tree

             admin_user  <some uid>
             admin_group <some gid>

             www_user    <some uid>
             www_group   <some gid>
             www_server  repocafe.my-org.org
             www_secret  **********
             www_contact svn-admin@my-org.org

             db_host  pghost.my-org.org
             db_name  repocafe
             db_user  apache
             db_pswd  **********

             ldap my_tag ldap.my-org.org dc=my-org,dc=nl usual

             clas users  ldap my_tag ou=people my-org_users
             clas guests table repo_guests login passwd name

             # users and guests can create repositories

             tree EMPTY EMPTY users,guests

           Test the config by running "configtest".

           Program ccoonnffiiggtteesstt just loads the config ; any detected errors will
           be shown. Optionally, it connects to the database as the configured
           database user _d_b___u_s_e_r or _d_b___o_w_n_e_r. The program can also test the
           ldap connections(s).

             Usage: configtest [-v] [-q] [-d] [-u] [-o] [-t] [-l] [-V] [-R] [-a] [-c conf]
             option v : be verbose
             option q : be quiet
             option d : show debug info
             option u : also try to connect to the database as ’db_user’
             option o : also try to connect to the database as ’db_owner’
             option t : also try to check the database has all the tables
             option l : also try to bind to all the ldap servers
             option a : test all : implies -u -o -t -l
             option c : use config file <conf>
             option V : show repocafe version  ; exit
             option R : show repocafe revision ; exit
             ----------------------------------------
             - configtest - test the repocafe configuration.
             - Program configtest just loads the config ; any detected errors will be shown.
             - Optionally, configtest connects to the database as the configured database
               user db_user or db_owner.
             - The program can also test the ldap connection(s).
             ----------------------------------------

       * _s_e_t_u_p_-_d_a_t_a
           Run sseettuupp--ddaattaa to setup the various files and directories.  It
           should run as root so it can chown stuff to _w_w_w___u_s_e_r/_w_w_w___g_r_o_u_p.

             Usage: setup-data [-v] [-q] [-d] [-f] [-c conf]
             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>
             ----------------------------------------
             - setup-data - setup the repocafe data.
             - setup-data creates and/or chowns the configured data files and directories.
             - setup-data must run as root or the configured <www_user>, unless in dry-runs.
             ----------------------------------------

       * _s_e_t_u_p_-_v_h_o_s_t
           Run sseettuupp--vvhhoosstt ; it shows (on STDOUT) the suggested vhost setup.
           Catch the output and use it to set up an appropriate apache vhost.
           Use "-a" to see the suggested apache _a_u_t_h_c_o_n_f_i_g.

           You may have to tweak the vhost and auth configs to make them fit
           in your distro’s default apache setup.

             Usage: setup-vhost [-v] [-q] [-d] [-a] [-c conf]
             option v : be verbose
             option q : be quiet
             option d : show debug info
             option a : show the ’authconfig’ config
             option c : use config-file <conf>
             ----------------------------------------
             - setup-vhost - show the suggested repocafe vhost or auth apache config.
             - setup-vhost generates apache configs from templates ; you may have to
               tweak them.
             - The generated configs must be placed in the apache config tree ;
               the precise locations depend on the distro/apache installation.
             ----------------------------------------

       * _s_e_t_u_p_-_d_b
           If you own the repocafe database, you can use program "setup-db" to
           setup the repocafe tables.

           If not, you can send your DBA the output of

             setup-db -sql

           and she can create the tables for you.

           Please note:

           1 program _s_e_t_u_p_-_d_b should only be used during setup and upgrades
           2 always do dry-runs before forcing action with option "-f"

           Program "setup-db" checks the database for the presence of required
           tables, contraints, triggers etc.

           After doing a dry-run, create/fix the database setup with option
           "-f".  When upgrading, make a backup of your database before you
           use program "setup-db" ; always use dry-runs.

           RReeppooccaaffee requires that database-language _p_l_p_g_s_q_l is enabled for the
           repocafe database. To check if it is, use :

             SELECT * FROM pg_catalog.pg_language WHERE lanname = ’plpgsql’

           Program "setup-db" will attempt to _c_r_e_a_t_e the language, if it is
           not enabled for your database :

             CREATE LANGUAGE plpgsql

           but may lack permission. To avoid the problem, make sure language
           "plpgsql" is enabled for the repocafe databse, _b_e_f_o_r_e running pro-
           gram "setup-db" :

           1 use program "psql" to check :
                 SELECT * FROM pg_catalog.pg_language WHERE lanname = ’plpgsql’ ;

           2 if the selection is empty, attempt to _c_r_e_a_t_e the language
                 CREATE LANGUAGE plpgsql ;

           3 if you lack permission, ask your DBA to _c_r_e_a_t_e the language.

             Usage: setup-db [-v] [-q] [-d] [-f] [-sql] [-c conf] [ table ]
             option v   : be verbose
             option q   : be quiet ; print only sql commands
             option d   : show debug info
             option f   : action ; otherwise dry-run
             option sql : just show the sql to be executed
             option c   : use config-file <conf>
             argument table : only process <table> (unless -sql is specified)
             ----------------------------------------
             - setup-db - setup the repocafe database tables.
             - Program setup-db creates missing tables, foreign key constraints etc.
             - After doing a dry-run, create the database setup with option -f.
               If, during setup, you change your config, re-run setup-db.
             - Use ’setup-db -f’ with care, after setup is complete.
             ----------------------------------------

       * _u_p_d_-_a_d_m_i_n_s
           Define repocafe admins with "upd-admins".

           Normally, only the configured _d_b___o_w_n_e_r can do actual add/deletes,
           and database user "db_user" can only do SELECT and UPDATE on the
           _r_e_p_o___r_o_o_t_s database table. However, if _d_b___o_w_n_e_r or _d_b___o_p_s_w_d is
           empty or not configured, the _d_b___u_s_e_r, _d_b___p_s_w_d username and password
           are used by "upd-admins".

           Before an admin is added, the specified admin login is looked up.

             Usage: upd-admins [-v] [-q] [-d] [-f] [-del admin] [-add admin] [-c conf]
             option v   : be verbose
             option q   : be quiet
             option d   : show debug info
             option f   : action ; otherwise dry-run
             option del : delete admin <admin>
             option add : add admin <admin>
             option c   : use config-file <conf>
             ----------------------------------------
             - upd-admins - create/delete repocafe admins.
             - By default, upd-admins lists the current admins.
             - Normally, only the configured db_owner can do actual add/deletes, and
               database user db_user can only do SELECT and UPDATE on the repo_roots
               database table. However, if db_owner or db_opswd is empty or not
               configured, upd-admins uses db_user/db_pswd for the database-connection.
             - Before an admin is added, the specified admin login is looked up.
             ----------------------------------------

       * "local.ppp"
           Check the contents of file "dir_www/local.ppp" (created by
           "setup-data") ; it should contain the full pathname of the config
           file ; for example :

             <?
             $CONF_ROOT = ’/home/repocafe/repocafe.conf’ ;
             ?>

           Make sure the apache/php config allows php scripts to read the con-
           fig file.

       ffiinniisshh

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

       * viewvc
           Install package viewvc, or do it later ; nothing depends on it.
           You can (temporarily) configure

             no_viewvc

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

       * php package "jpgraph"
           Install php package jjppggrraapphh ; this should work :

             require_once ’jpgraph/src/jpgraph.php’ ;
             require_once ’jpgraph/src/jpgraph_line.php’ ;

           Package jjppggrraapphh is used in "plot.php".

       * "gnuplot"
           Make sure program "gnuplot" is installed ; it is used by "mk_stats"
           to plot the data.

       * cron jobs
           Remember to setup cronjobs for "mk_stats" and "upd-xusers".

             42 05 * * * ( cd <dir_admin> ; /usr/bin/perl mk_stats -f )
             44 05 * * * ( cd <dir_admin> ; /usr/bin/perl upd-xusers -f )

       * mail alias
           You may want to set an email alias for the configured "www_con-
           tact".

       * configuration
           If you have configured a (non-EMPTY) _d_b___o_w_n_e_r and _d_b___o_p_s_w_d, you can
           now remove them from the config.  You will have to put them back in
           later, if/when you want to add or delete svn-admins with
           "upd_admins".

       * feedback
           If you got this far, please send some feedback to the authors
           (repocafe@cs.uu.nl).  What was the hardest part of setting up the
           cafe ?  What was unclear (or wrong) ? Ideas for improvement ?

AADDMMIINNIISSTTRRAATTIIOONN
       After setting up a repocafe, there is not a lot to do for the admins.
       Here are a few points an admin should know :

       * active / inactive
           When you (an admin) login, you are either _a_c_t_i_v_e or _i_n_a_c_t_i_v_e (as an
           admin). When _a_c_t_i_v_e, you have full admin rights ; when _i_n_a_c_t_i_v_e
           repocafe treats you as it would any other user.

           When you are logged in, every page shows a button with which you
           can switch between _a_c_t_i_v_e and _i_n_a_c_t_i_v_e.

       * guest accounts
           Use config_option "create_guests" to specify which user classes are
           allowd to create guests.

           Guest accounts are created by web form. You only need to specify a
           _f_u_l_l _n_a_m_e and an _e_m_a_i_l _a_d_d_r_e_s_s. A login-name is generated from the
           _f_u_l_l _n_a_m_e ; the login-name and a random password are mailed to the
           guest.

           When a guest tries to login, and her password fails, the guest can
           request that her password is sent to her (again).

           A logged-in guest can change her password.

       * repositories on request
           If you have structured your repository names, and the config has
           tree-lines without user-classes, then repositories in those trees
           can only be created _o_n _r_e_q_u_e_s_t ; that means you, because only the
           admins can create them.

       * cleanup the archive
           When a user or admin deletes a repository, the repository is moved
           from "dir_data/repos/" to "dir_data/archive/". The repository’s
           name is suffixed with a number, so deleting more than one reposi-
           tory with the same name, doesn’t give a name conflict in
           "dir_data/archive".

           On deletion, the repository directory is _t_o_u_c_h_e_d, so with "ls
           -lart" you can list (and remove) the archived repostories by dele-
           tion date.

       * cleanup repositories
           In the _s_t_a_t_i_s_t_i_c_s _p_a_g_e, there is a list of _r_e_v_i_s_i_o_n _0 repositories
           : repositories that were created, but were used to put stuff in.
           The list is ordered by date. You may want to delete them after some
           (fixed, announced) time.

           The statistics page also has lists of _u_n_u_s_e_d _g_u_e_s_t_s and _u_n_u_s_e_d
           _g_r_o_u_p_s ; _u_n_u_s_e_d meaning _u_n_r_e_f_e_r_e_n_c_e_d.

       * cleanup ex-users
           An _e_x_-_u_s_e_r is a login-name that appears in a repocafe (as owner, in
           the repository rights, or as group member) but can’t be found in
           the cafe’s guest list or ldap(s).

           The statistics page shows a list of repositories owned by ex-users.

           The statistics page also shows a list of ex-users holding access
           rights and/or group memberships. For every ex-user you see :

           1 the _r_e_p_o_s_i_t_o_r_i_e_s where the ex-user has access rights,
           2 the _g_r_o_u_p_s where the ex-user is a member,
           3 a button to remove all the ex-user’s access rights and group mem-
           berships.

WWIISSHHLLIISSTT
       Here are a few things we would like to add to "Repocafe" :

       * support for other versioning systems, like "git"
       * support for other database systems besides "postgresql"
       * support for authentication based on "active directory"
       * support for _d_i_s_k _q_u_o_t_a ; "lock" users who are exceeding their quota
           A base quotum per user-class ; plus a quotum per user.

AAUUTTHHOORR
         (c) 2010 - 2016 Koos van den Hout -- Henk P. Penning
         k.vandenhout@uu.nl -- http://idefix.net/
         penning@uu.nl -- http://www.staff.science.uu.nl/~penni101/
         ICT-beta, Faculty of Science, Utrecht University
         repocafe version 0.13.6 - Tue Jan 19 16:00:37 2016 - revision 257


perl v5.8.8                       2016-01-19                       REPOCAFE(1)