Skip to content

SetupDocDB

Jump to bottom Edit New page
Alex Drlica-Wagner edited this page Aug 18, 2020 · 1 revision

Customizing DocDB

  1. Login to the document database account.
  2. This account is used to administer the various DocDB scripts and html pages.
  3. Checkout DocDB from GitHub as described elsewhere (if you haven't already).
  • cd to DocDB/cgi
  • cp ProjectGlobals.pm.template ProjectGlobals.pm
  • cp ProjectMessages.pm.template ProjectMessages.pm
  • cp ProjectRoutines.pm.template ProjectRoutines.pm
  • cp ProjectHelp.xml.template ProjectHelp.xml
  • Edit the global variables in ProjectGlobals.pm. You can also look at DocDBGlobals.pm and put new values for those variables in ProjectGlobals.pm.
  • Customized web page headers and footers are defined in ProjectRoutines.pm.
  • If you need a customized keyword message, edit ProjectMessages.pm.
  • If you need customized help instructions, edit ProjectHelp.xml
  1. Check the files in DocDB/html. copy the files in DocDB/cgi to $script_root (your private DocDB cgi directory) $script_root is defined in ProjectGlobals.pm, it is not an actual environmental variable. (If you installed from the git repository, you can use the command git pull to update the running software here.)
  2. If you are using HTTP Basic Authorization, create a .htaccess file in $script_root. If you are using client certificate authorization, you can skip this step.
  • Here is a sample .htaccess file:
       AuthType Basic
       AuthName "My Document Database"
       AuthUserFile  /somedir/somedir/.htpasswd
       < Limit GET POST >
       require valid-user
       < /Limit >

The .htpasswd file should not be in any web-accessable directory. Also, the POST option must be present or DocDB will not work (most of the form posts to cgi scripts will fail).

  1. Setup the documentation and Cascading Style Sheets with the command
cp -r DocDB/html $file_root/Static

where $file_root is defined in ProjectGlobals.pm.

  1. Set permissions on $file_root. $file_root must be owned by the uid/gid of the webserver process. DocDB will create the necessary subdirectory structure and populate it with the downloaded files when documents are created and edited. Unlike the remainder of $file_root, the $file_root/Static directory tree must be owned by the document database account.

  2. Create the public access scripts. The suggested way to do this is to create a directory where the relevant scripts (some scripts have no valid public use) are links to the corresponding private scripts. In this configuration, two additional files must be present in the public area: ProjectGlobals.pm and CGIInclude.pm.

  • mkdir /www/cgi-bin/public/DocDB/, chosing an appropriate directory for the public scripts.
  • cp DocDB/scripts/PublicInstall.csh /www/cgi-bin/public/DocDB/.
  • cp DocDB/cgi/ProjectGlobals.pm /www/cgi-bin/public/DocDB/. This script will make links to the private DocDB cgi area. Edit this script as necessary.
  • Execute PublicInstall.csh.
  • rm PublicInstall.csh
  • Edit the public ProjectGlobals.pm, taking particular care to be sure these definitions point ONLY to the public directories. Be sure to remove the $Administrator definition from the public ProjectGlobals.pm. Uncomment the "Public" lines in ProjectGlobals.pm.
  • Copy CGIInclude.pm from the scripts/ directory and edit it to point at your main installation. This is needed to pick up the DocDB .pm files.
  • Edit your Apache httpd.conf file and make sure FollowSymLinks is added to the Options for this directory.
  1. mysql SomeDocDB -u docdbadm -p < DocDB/sql/CreateDatabase.SQL
  2. If you are using client certificate based authorization:
  • Edit the apache config files to require a client certificate for the $cgi_root/$web_root directory. (See SSL and DocDB for an explanation of this.)
  • Make sure the client certificates you are using are from a CA you trust.
  • As the administrator, import your certificate into your web browser if you haven't done so.
  • Point your web browser at $web_root/DocumentDatabase. Follow the link to request access and request access in the docdbadm (or DocDBAdm) group and whatever other groups you would like to access.
  • Now you have to verify that you are an administrator. The easiest way to do this is to start mysql in shell mode (mysql -h xxxx -u docdbadm -p SomeDocDB), then do the following: mysql> select EmailUserID,Name from EmailUser; and find the EmailUserID of the desired administrator (should be "1" unless you've done something strange). mysql> update EmailUser set Verified=1 where EmailUserID=x; where "x" is the number from the previous step (1).
  • Again, point your web browser at $web_root/DocumentDatabase. You should no longer see a message indicating that you are need to request access. If you follow the "Create or Change Documents..." link, you should have access to all adminstration functions.
  1. At this point, you can verify that DocDB is running properly. Point your web browser at $web_root/DocumentDatabase and log in as administrator if necessary. From here you can follow the "Create or Change Documents..." link, where you should have access to all adminstrative functions. Use the administrator functions to create topics, authors, other security groups, etc.
  2. mkdir $file_root/Static/Lists
  3. mkdir $file_root/Static/Lists/group-name for every permission group defined in DocDB.
  4. Setup the listing and notification cron jobs
  5. Customize CSS files: The appearance of many pages in DocDB is controlled by CSS (Cascading Style Sheets). The .css files reside in $file_root/Static/css. The naming scheme is as follows:
  • DocDB.css -- The CSS file with global and common settings for all pages.
  • DocDB_IE.css -- Changes to the master setting for Internet Explorer, which has broken CSS support.
  • DocDBSomeScript.css -- CSS unique to a particular page
  • DocDBSomeScript_IE.css -- Changes to the CSS for a page needed by IE

To any of these scripts you can make your own changes. Append MyProject to the original name of the CSS file and it will be included after the DocDB defaults, changing any settings. MyProject is what you set $ShortProject to in ProjectGlobals.pm. For example, if your project is "Joe" and you want to change the settings for the IE only CSS for the ShowDocument page, create a file JoeDocDBShowDocument_IE.css and place it in the $file_root/Static/css directory.

See html/css/ProjectDocDB.css.example for examples of what might be changed. Note that not all pages have CSS files and that at this time, and that use of CSS in DocDB is new but expanding.

Add a custom footer

Home

  1. Installing DocDB

Clone this wiki locally