4 AdminManual
Izzy edited this page 4 years ago

Administration Manual

This part of the documentation is dedicated to the site administrator, and deals with things to be done on the server. The following issues will be covered:

More issues for the site admin you will find in the CustomizationManual.

Installation

Requirements

There are a few dependencies to consider in order to use phpDiveLog:

  • a Web server supporting PHP (tested only with Apache)
  • PHP5+ (recommended: PHP 5.2+ as loadable module for Apache - which again is the only tested variant), with the php-bcmath module
  • optional (for PDF support with PDL v0.3.5+) TCPDF (PHP PDF Api)
  • optional (for language negotiated help pages) php5-curl

Most (if not all) Linux distribution ship the requirements along with their package manager, so it should be easy to install. On Windows it might be a bit more tricky. To test whether you meet these requirements, simply create a test PHP file containing a single line: <?php phpinfo();?>, put it into your document root, and call it with your browser. The resulting page will list your PHP configuration and tell you about available capabilities.

Concerning the optional TCPDF, you can grab the full distribution from their site for manual installation (which will be the only way with Windows), or use our repository (see below) for *.deb/*.rpm packages. The minimal case here includes the packages tcpdf-api plus tcpdf-fonts-minimal, but we recommend to replace the latter with tcpdf-fonts-basic for better UTF8 support with the available fonts. Still, the recommended variant is just ~4MB packed size – opposite to >10MB of the original distribution archive.

Installation

The best (and most recommended) way to install [wiki:phpDiveLog] is to use your Linux distributions package manager. There are *.deb and *.rpm packages available in the IzzySoft APT repository, and you can even include this repository in your APT or YUM configuration (this is described on the webpages there). Doing so, all dependencies will be resolved automatically, and installation is done by a single command (apt-get install phpdivelog or yum install phpdivelog will perform all necessary steps - for the TCPDF Api, add apt-get install tcpdf-api tcpdf-fonts-basic resp. yum install tcpdf-api tcpdf-fonts-basic).

If you can neither use *.deb nor *.rpm packages, you should download the TAR archive. Having these unpacked, change to the directories created and run make install after making sure that all dependencies are met.

All these mentioned methods have at least two advantages over the manual installation:

  • all files will automatically be put to the right places
  • everything can be easily cleanly uninstalled (apt-get remove phpdivelog, yum remove phpdivelog, make uninstall)

Using *.deb/*.rpm packages with the repository moreover will allow you easy updates.

Manual Installation

If you prefer to do a manual installation, you first need to make sure all [#Requirements requirements] are met. Then:

  1. Unpack the TAR archive to the directory of your choice. This must either be inside your web servers document root, or linked there (and the web server configured to allow that – FollowSymLinks in the Apache options), or set up in your web servers configuration as an Alias
  2. (Re)Move the install/ subdirectory from that installation, since it is not needed on the server but rather on the clients. Details on this can be found in the [wiki:DiverManual].
  3. If you are concerned about disk space, you may want to remove language files for languages which you don't need (lang/trans.*). This will free some hundred kilobyte at maximum. And you must not delete the English language file (lang/trans.en), since this is the only one really required.

Help Cache

Depending on the installation path chosen, you may have to check for the cache/ directory, which needs to be read- and writeable by the web server process. When installing from a package, the .deb/.rpm stuff should have taken care for this - but it cannot hurt to make sure. If you forget this step, don't worry: The help system will let you know :)

Updating

Depending on how you performed the installation, updating from a previous version of [wiki:phpDiveLog] can be done in different ways:

  • Using your package manager (apt-get update phpdivelog, yum update phpdivelog
  • using the Makefile (make install)
  • manually copying the files from the Tar archive

Configuration

How to best configure phpDiveLog

Configuration of the web application mostly takes place in text files, and for the system wide configuration the relevant file is inc/config.inc. To provide you with an easy way for updates to later versions, where this file could be replaced, there is a special feature: If found, inc/config_local.inc will be included right after inc/config.inc and overwrite its settings. So if you want to change some settings, the best way is:

  1. copy inc/config.inc to inc/config_local.inc
  2. remove all settings you do not intend to change from config_local.inc. Feel free to remove all comments as well.
  3. now, in config_local.inc adjust the remaining settings to the preferred values. Big advantage of this: If there comes an update and introduces new settings, they will take effect via the new inc/config.inc - while your customized settings in inc/config_local.inc remain untouched.

Settings explained

General Settings

Some of the General Settings can be overridden by URL parameters, which is especially useful if you plan to access the dive log(s) in two different ways: directly (stand-alone), where you have the full browser window available for PDL, and integrated in a frame of your website, where space is a bit limited. So in the latter case you don't care about additional URL parameters to limit e.g. the rows per page in lists, while in the first case you want to use the additional space and have longer lists. The column URL Override tells you the parameter name, if available.

Setting Default URL Override Explanation
$database!["type"] "csv" - in which way the divers data will be provided. Right now you can set this to "csv" only. In the future, there may be more formats available, such as UDDF for the Universal Dive Data Format (again a file), or even "real databases" such as MySQL, PostgreSQL, etc.
$display_limit 12 displaylimit with pages containing lists, as e.g. the sitelist, this value will advise PDL how many entries (i.e. table data rows) to display per page. This saves you from scrolling through long pages – but of course you can set this to e.g. 999999999 and everything will fit on one page (but not necessarily one screen).
$template_set "aqua" tpl to which template set PDL should default. Right now the values "aqua" and "default" are available. The visitor can overwrite this value (for his/her browser session only, of course) by selecting a different template set on the preferences page.
$lang "en" lang the default language to use (if no other language was specified via the users preferences). This is a 2 character ISO code, like "en" for English or "de" for German. You can set this to any language you like - if no translations are found, PDL will fall back to English. You can tell available languages by investigation of the lang/ directory. See the CustomizationManual for details on how to add missing translations.
$title "Demos phpDiveLog" - for now the site name to be displayed in the browsers title bar. At the end of this, some page information will be added: if you e.g. set the title to "MyDiveLog", by browsing the dive #5 the browsers title probably looks like "MyDiveLog: Dive# 5" - where "Dive" could be localized even …
$enable_index TRUE - whether visitors should be allowed to browse the buddylist. Needs to be set to "TRUE" if you want to use $default_page="index" (see below).
$default_page "user" - what to do if there's no diver specified with the URL (and thus PDL does not know where to look for the data - normally this has to be done on the URL with the diver=nickname parameter)? Available options are "user" ($default_user must be set to a valid user then), "index" (display the index page with available nicks, needs $enable_index=TRUE - see above), and "error" (display an error message to the visitor)
$default_user "demo" - only evaluated if $default_page="user": which is the default logbook we should route the request to? Must be a valid account, otherwise results in $default_page="error".

Geographical Stuff

Setting Default Explanation
$mapsite "Google" If you recorded GPS coordinates with your dive sites, phpDiveLog creates a link to a given mapsite to look up the place. You may chose between "Mapquest" and "Google" (the latter refers, of course, to Google Maps)
$global_kml TRUE The "global KML file" lists all available divers KMZ files as "network links" (one link per diver) - which works fine with Google Maps. Google Earth, however, seems to request all listed network links simultaneously - which the server may interprete as DoS attack and reject some of the requests (the user can, however, reload missing files manually then in most cases). So if you are affected by this, you may turn the global KML processing off here.

Graph Settings

Setting Default Explanation
$sitepix_on_divepage 0 if you want pictures from the corresponding dive site to be generally displayed together with the pictures from the dive when viewing the dive page, set this to 1.
$sitepix_first 0 only has effect with $sitepix_on_divepage not set to "0" and decides whether site pictures precede the dive pictures (1) or follow them (0)
$sitepix_separate 0 only has effect with $sitepix_on_divepage not set to "0" and decides whether they are separated from the dive pictures (1) or simply added (0)
$sitepix_if_no_divepix 1 only has effect with $sitepix_on_divepage not set to "0" and decides whether site pictures will be included on a dive page if there are no dive pictures available. Other than with $sitepix_on_divepage, this would not include site pictures on the dive page if there are dive pictures available.
$use_dyn_profile_png 0 Though the Aqua DiveLog Conduit creates graph images for the dive profiles, these images vary much in their dimensions. To keep the design more clear, you may want to generate these profiles dynamically by setting this option to "1" (see also DynamicGraphs). Note that this requires GD support in your PHP installation - plus a directory named profiles in each divers home, writable for the web server process. The image then will be generated in two cases: If it does not already exist, or if the profile CSV file is newer.
$schedule_graph "integrated" These graphs are not provided by the conduit, so phpDiveLog will have to generate them if you want them (which means, $use_dyn_profile_png must be enabled for this - see also DynamicGraphs). With the $schedule_graph configuration option, you can tell phpDiveLog how you want your schedule graph to be drawn: "integrated" into the profile graph (if possible, falls back to next otherwise), as a "separate" graph in the Schedule section of the page, or "none" if you don't want it at all.
$hide_schedule_table TRUE Since the graph says more than thousand table rows, you may not want to waste space on the page for the raw data. Here you can decide whether to hide (TRUE) or display (FALSE) them.
$values_in_statgraphs "auto" On the statistics page for each diver you also find some graphs, e.g. for dives per year. They can have the values printed within the bars – but if you are to list up statistics for more than 20 years, or have several hundreds (or even more) dives per year, this may not look as nice as you would expect - so you have the choice to: always have the values displayed in the bars ("yes"), never have them there ("no"), or let the app decide ("auto"). The latter should be fine for the average diver. Note: The values are always displayed when hovering the mouse over the corresponding bar - so don't be afraid they could be completely missing.
$graph_bg_transparent FALSE This setting decides whether to use transparent background for the graphs (TRUE) or not (FALSE).
$ignore_zero_degrees TRUE If you did not enter any water temperature in ADL, the conduit would export this as "0°C" - so phpDiveLog cannot decide between "no temperature entered" and "real 0°C". Though this temperature is really unlikely to be dived in, we want to leave you the questionable fun of doing so by setting this variable to FALSE.
$ignore_zero_degrees_comment TRUE If $ignore_zero_degrees was set to TRUE, shall we place a note below the temperature graph to indicate this?
$temp_stat_interval 10 Temperature intervals for the corresponding statistics graph. You may set this to either 5 or 10.
$time_stat_interval 10 Time interval (in minutes) for the Dives by Duration graph. Set this to either 10 or 20 (30 should also work).
$depth_stat_interval 5 Interval (in meters) for the Dives by Depth graph. Valid settings are 5, 10, and 20.

Data Transfer Settings

Setting Default Explanation
$pwdfile "/etc/pdlpwd" If you want to allow your buddies to transfer their divelog data using a single OS account (see MultiUser Issues), you need to set up a password file (so only the diver him-/herself can import their transfered data into the PDL installation). This file should NOT reside inside your web tree, but it must be readable by the web server. A good idea is to let this file be owned by the web servers users group, and apply read permission for the group. The web server should not have write permission to the file.
$transfer_dir "/home/pdl/transfer/" The base directory for the transfered logbook data when using the "single OS user transfer" (see MultiUser Issues). This should be the directory containing the diver directories directly below it (i.e. the counterpart to the PDL diver/ directory).

Sorting and Ordering

These are the default sort settings if one enters the logbook resp. sitelist first time on the visit, and did not yet apply a custom sort (i.e. did not yet click one of the up/down arrows next to the column names). The *_order can be either "asc" or "desc". For the *_sort are the following values valid:

  • logbook: date, time, location, place, rating, depth, buddy
  • sitelist: location, place, depth

As with some of the General Settings, you can override these with URL parameters.

Setting Default URL Override Explanation
$logbook_default_sort "date" sort Sorting the logbook (dive list)
$logbook_default_order "desc" order Ordering the logbook
$sitelist_default_sort "location" sort Sorting the site list
$sitelist_default_order "asc" order Ordering the site list

PDF Settings

If these settings shall have any effect, you need to have TCPDF installed on your server. You can download and install the full distribution from their site (>10MB zipped size), or decide to install the "stripped variant" from the IzzySoft APT/YUM repository (minimal install: ~1MB, including the API plus the font definitions – recommended install: ~4MB, including the API and the basic fonts), if your system supports *.deb or *.rpm packages. (Note: the packages in the repositories have not been updated for a while, and probably won't be updated soon).

Setting Default Explanation
$tcpdf_path "/usr/share/tcpdf/" Where the TCPDF files are installed. If you installed TCPDF from our repository, you don't need to touch this.
$pdf_page_format "A5" Page size to use for PDF. Valid settings are everything between A0 to A5 and B0 to B5. The default (A5) should be a good choice together with the detault for $pdf_page_orientation (Portrait), since you can easily print two pages on one A4 page then (letting the printer driver print 2 pages on one with multiple pages exported, it should be able to handle duplex as well).
$pdf_page_orientation "P" Orientation of the page: Portrait or Landscape. The default assumes you want to print two A5 pages on one piece of A4 paper. If you have trouble to convince your printer, try A4 with landscape.
$pdf_page_gutter 25 Space to be used to file the pages into your book. PDL takes care to have it on the right side of the pages (left for odd, right for even numbers)
$pdf_page_margin 5 Space on the side opposite to the gutter
$pdf_no_profile "dummy" What shall be used for the dive profile if we have none available: "dummy" places a "dummy profile", "blank" just leaves the space blank.
$pdf_with_fotos TRUE Would you like to have some photos included with your logbook pages (if there are dive photos connected)? Setting this to TRUE will include the first three dive photos (if available), or all dive photos if there are less than three.
$pdf_enable TRUE Whether PDF functions should be available (if the API is found then). You can use this option to disable PDF support when you feel "too many users on the public servers play with it, and the server load increases too much", for example.
$pdf_max_notechars 1900 To make sure the notes fit in the template, they will be truncated when exceeding this value
$pdf_chars_per_pix 10 For each 10px picture height, we lose one line of text space - which is about 100 chars, and thus corresponds to 10 chars per pixel
$pdf_create_missing_graph 1 Missing profile graphs can be created on-the-fly when generating the PDF - so this setting can be overridden on the page for "mass-export". If set to "1", missing (and outaged) profiles will be (re)created. If set to "0", the static graph will be substituted (if found), or the setting of $pdf_no_profile will be applied.

Configuration Overrides by Divers system.conf

Setting Default Explanation
$override_protection "explicit" How to tell which settings may be overridden by the divers system.conf settings. "implicit" means the behaviour as it has been until v0.4.0: all configuration variables except for those specified by $allow_override have been "protected" (i.e. the divers could not override them). In a less restrictive environment, the $allow_override list could get quite long - hence the new default is "explicit": all configuration variables can be overridden by the divers system.conf - except for those explicitly mentioned in $protected_options
$allow_override (depends on version) here we define which configuration variables may be overridden by the diver/*/system.conf file (see divers configuration) when $override_protection is set to "implicit". The value of this parameter is a space separated list of options – and is completely ignored when $override_protection is set to "explicit".
$protected_options (depends on version) which configuration variables may not be overridden when $override_protection is set to "explicit" (otherwise, this setting is completely ignored). As $allow_override, this is a space separated list.

Debug Settings

Setting Default Explanation
$debug_level "EW" What information shall be logged. This can be a combination of events (chose the bold letter): Errors, Warnings, Notices, All. By default, errors and warnings should be reported. Notices may be useful for debugging purposes.
$debug_show 0 Whether debug info should be displayed in the browser window itself (1) - a very bad idea for "production" systems, since internal (private) information would be presented to each visitor. This is really simply to ease debugging – you should always turn it off (0) otherwise.
$debug_log 1 Whether to store error messages to the web servers error.log file (1) or not (0). It is always a good idea to have this turned on – so you can verify if a certain error already exists for a while, and since when.

Robot Settings

These settings are intended to handle search engine crawlers, and especially prevent their recursion through too many levels plus limit their visits, if possible:

Setting Default Explanation
$robots_index_lists "index,follow" How robots shall deal with lists (site list, dive list, buddy list). The default is set to not change the previous behavior: They shall keep the pages content in their databases (index), plus follow all links (follow). It could also be useful to set this to "noindex,follow" – since the lists themselves may not be that useful to the search engine visitor. Note, however, that "nofollow" could take the whole divelog away from engines respecting these settings.
$robots_index_pages "index,nofollow" Similar to above, but for the detail pages. Here it makes much sense to set nofollow, to prevent the crawlers from looping through everything – all useful information is contained on the page already.
$robots_index_prefs "noindex,nofollow" Makes absolutely no sense to give these pages to the search engines, so "noindex,nofollow" is the only useful setting here. However: If you feel different, you may change it here.
$robots_revisit_lists 14 After how many days a search engine crawler may return to check for updated content. We keep this a bit lower for lists, so new dive/site entries will make it into the search engines index. Note that not all crawlers respect this setting.
$robots_revisit_pages 60 Once the content has been set up, it's rarely subject to change – so you may even increase this value. If you, however, tend to change existing entries frequently, you may also decrease it.
$robots_revisit_prefs 9999 We don't want this content indexed – so we don't care if the crawler revisits them at all. Feel free to add a few digits :)

Miscellaneous Settings

Setting Default Explanation
$emoticon_file "inc/emoticons.csv" Emoticon definition file (see Emoticons). Comment out if you don't want to have emoticons to be used.

Diver Accounts

All things needed for a diver account can be found in the diver/ directory: Each subdirectory here represents a diver account, the name of that subdirectory represents the divers nick.

Directory Structure

Each divers directory contains a number of subdirectories with the following structure:

-+ data     (holding the *.csv data files)
 + fotos
 | + dive   (fotos of the dives)
 | + site   (fotos of the dive sites)
 + images   (dive profiles generated by ADL are placed here)
 + profiles (dynamically generated dive profile graphs)

All the directories require at least read permission for the web server process, the (optional) profiles directory additionally requires it to have write permission as well to store dynamically created graph image files. If you want to use phpDiveLogs "import" facilities (useful only with multiple divers you don't want to give access to the web tree), the web server requires read and write permission to all of these directories (see the MultiUser and Directory Permissions articles).

Setting up a new diver

To setup a new diver, you can use the shipped "demo" account as template. Just copy the diver/demo directory to diver/john, cleanup the data from the diver/john directory (i.e. all files from the data/, fotos/, and images/ subdirectories as well as from the profiles/*), and you've created a new account for "john".

For the divers configuration, please see the Divers Configuration article, since this is the divers task.

Directory Permissions

Generally, the web server process requires read permission on all directories and files of the phpDiveLog installation - otherwise it cannot serve the web pages. Depending on your configuration and intended use, it additionally will require write permission on certain directories:

  • diver/*/profiles for dynamically created graph images
  • full diver/* including all subdirectories and files in order to use the "data transfer with a single OS user" (see MultiUser), for those users you want to give this facility to
  • cache/ for the help system to work (which caches the information retrieved from this wiki there)

For all directories not explicitly mentioned to require write permission, you better leave them read only for the web server.

MultiUser Issues

Hosting more than one divers data rises some security related questions: Probably not all of them shall have write access to your web servers directories. Moreover, you might think about adjusting some configuration parameters.

Configuration

With only one diver, you probably will set the $default_page="user" and $default_user="<your_nick_here>", so every visitor comes directly to your log even without parameters in the URL string. With multiple users, this may be different. Possible variants include:

  • leave it the same since you are the most important user
  • change the default page: $default_page="index" so visitors coming without URL parameters will see a list of public nicks
  • change the default page: $default_page="error" to hide all of the divers and only grant access to those who know the right parameters

The most likely solution will be one of the first two, I guess.

Data Transfer

Here we can again think of multiple solutions:

  • all users have direct access to their directories, either
    • they have access to the full web tree
    • you set up FTP users for each and "chrooted" them to their directories
  • all users have access to their own FTP account elsewhere on the server
  • all users have access to a common single OS/FTP account

The first case is easy: Everybody simply transfers the data directly to the divers directory. No additional actions required.

The other two options require some special action: Either all their "home directories" are located directly in the same "base directory" (i.e. the $transfer_dir defined in the inc/config.inc, see Configuration), or you achieve this using symlinks. After the users uploaded their data, they need to call the import.php with their nicks used, where they need to enter the corresponding password to run the import.

So if the import module is to be used, passwords need to be setup in the $pwdfile you specified in the config.inc file. A sample password file is provided as install/etc/pdlpwd so you can see its structure. For each user requiring a password, just add the appropriate line – where the "pwd" is a md5 hash of the real password. This md5 hash can me calculated using the md5 executable on Linux/Unix machines, or using the PHP md5 command in a simple script, like echo md5("plain_text_password");.