Annotation of bookie/www/setup.html, revision 1.11

1.9       will        1: Setup instructions for compiling and running Bookie:
1.1       will        2: 
1.2       will        3: <p>
1.1       will        4: If you're just browsing or don't need to edit files directly, you can look
                      5: at Bookie through the <a
                      6: href="http://www.mozdev.org/source/browse/bookie/">web interface</a>.
1.8       will        7: 
1.9       will        8: <p>
                      9: If you want to contribute to Bookie or compile it, then you should grab a
1.4       will       10: CVS <a href="http://www.cvshome.com">client</a> and set up a workspace for bookie.
1.9       will       11: </p>
1.3       will       12: 
1.9       will       13: <p>
                     14: You download bookie by doing this (you only need to login once, the password
                     15: is guest).  Please use the prune option when checking out and updating, since
                     16: the CVS tree has a lot of dead branches in it.
                     17: </p>
1.1       will       18: 
1.2       will       19: <pre>
1.1       will       20:  cvs -d :pserver:guest@mozdev.org:/cvs login
1.9       will       21:  cvs -d :pserver:guest@mozdev.org:/cvs co bookie -P
1.2       will       22: </pre>
1.1       will       23: 
1.9       will       24: <p>
                     25: The java client is in <code>/clients/swing</code>.  There is an
                     26: <a href="http://jakarta.apache.org/ant">ant</a> script that should compile
                     27: everything.  The client depends on Jena, Apache XML-RPC, Log4J and Xerces.
                     28: All the libraries should be available in lib.  The client's main class is
1.11    ! will       29: <code>com.tersesystems.bookie.client.Client</code>.  Downloading
        !            30: <a href="http://tersesystems.com/bookie/client.jar">client.jar</a> will give you
        !            31: the classes, source code and javadoc to play with.
1.9       will       32: </p>
1.8       will       33: 
1.9       will       34: <p>
                     35: The java server is in <code>/server</code>.  Again, the
                     36: <a href="http://jakarta.apache.org/ant">ant</a> script that should compile
                     37: everything.  The server currently depends on JTidy, Marquee XML-RPC, 
                     38: Jisp, Servlet 2.2, Log4J, and Xerces, which are all available in lib.  The
                     39: server's main class is <code>com.tersesystems.bookie.service.xmlrpc.BookieServlet</code>.
                     40: </p>
1.4       will       41: 
1.9       will       42: <p>
                     43:   The server will create four files on initialization in the current directory:
                     44:   <ul>
                     45:     <li>profile.db - a database of profile information.</li>
                     46:     <li>profile.idx - an index of profile.db</li>
                     47:     <li>bookmarks.db - a database of bookmarks information.</li>
                     48:     <li>bookmarks.idx - an index of bookmarks.db</li>
                     49:   </ul>
                     50:   These databases contain all the information needed for the server to work.  Deleting
                     51:   these files will cause the server to start off fresh.  
                     52: </p>
1.7       will       53: 
1.9       will       54: <p>
                     55:   The server also starts up with a large amount of debugging information.  You can
                     56:   override the default configuration by specifying the log4j configuration file on
                     57:   the command line with <code>-Dlog4j.configuration=minimal.txt</code> where the 
                     58:   file <code>minimal.txt</code> contains the following:
                     59: </p>
1.1       will       60: 
1.9       will       61: <pre>
                     62:     # Set root logger level to INFO and its only appender to A1.
                     63:     log4j.rootLogger=INFO, A1
                     64:       
                     65:     # A1 is set to be a ConsoleAppender. 
                     66:     log4j.appender.A1=org.apache.log4j.ConsoleAppender
                     67:       
                     68:     # A1 uses PatternLayout.
                     69:     log4j.appender.A1.layout=org.apache.log4j.PatternLayout
                     70:     log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
                     71: </pre>
1.1       will       72: 
1.9       will       73: <p>
                     74:   The server does not attempt to limit multiple logins on the same account
                     75:   from different servers.  However, care should be taken with this feature,
                     76:   as there is no facility to distribute messages between clients that a 
                     77:   branch has been deleted.  
                     78: </p>
1.1       will       79: 
1.5       will       80: <p>
1.11    ! will       81:   Bookmarks are cached on the server, but since bookmarks are unique to 
        !            82:   each client this isn't that much of a win.  Performance seems okay for now 
        !            83:   (and if anything seems bound on the XML 
1.9       will       84:   processing and IO overhead).  Database operations are not transactional.
                     85: </p>
1.10      will       86: 
                     87: <p>
                     88:   The server uses an MD5 hashed password for authentication of the client.
                     89:   Once authenticated, the server maintains a session based off the IP address
                     90:   of the client.  All data is sent in the clear, and as such the passwords and
                     91:   XML-RPC information may be 
                     92:   <a href="http://www.robertgraham.com/pubs/sniffing-faq.html">packet sniffed</a>. 
                     93:   Even if the attacker does not know
                     94:   the clear-text password, he can still send the MD5 hash to be authenticated as
                     95:   the user.  Unfortunately, XML-RPC does not cover 
                     96:   <a href="http://www.strongsec.com/tutorials/security.htm">security</a> and session management
                     97:   very well; if there are any new RFCs I would love to hear about them.  One
                     98:   possible RFC is <a href="http://jimfl.tensegrity.net">Jim Flanagan's</a> 
                     99:   <a href="http://jimfl.tensegrity.net/xmlrpc/">proposal</a>, but this requires
                    100:   the use of <a href="http://www.ietf.org/rfc/rfc2617.txt">HTTP digest 
                    101:   authentication</a>, which I believe most clients don't
                    102:   support.
                    103: </p>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>