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:
- Installation: How to install phpDiveLog
- Configuration: Configuration Issues
- Setting up a diver: How to setup a diver
- Directories: Directories and their permissions
- MultiUser: Multi User Issues
More issues for the site admin you will find in the CustomizationManual.
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
- 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
*.rpm packages. The minimal case here includes the packages
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.
Recommended Installation Path
The best (and most recommended) way to install [wiki:phpDiveLog] is to use your Linux distributions package manager. There are
*.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
*.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,
*.rpm packages with the repository moreover will allow you easy updates.
If you prefer to do a manual installation, you first need to make sure all [#Requirements requirements] are met. Then:
- 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 –
FollowSymLinksin the Apache options), or set up in your web servers configuration as an Alias
- (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].
- 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.
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 :)
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
- manually copying the files from the Tar archive
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:
- remove all settings you do not intend to change from
config_local.inc. Feel free to remove all comments as well.
- now, in
config_local.incadjust 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
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.
||"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.|
||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).|
||"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.|
||"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
||"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 …|
||TRUE||-||whether visitors should be allowed to browse the buddylist. Needs to be set to "TRUE" if you want to use
||"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" (
||"demo"||-||only evaluated if
||"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)|
||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.|
||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.|
||0||only has effect with
||0||only has effect with
||1||only has effect with
||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
||"integrated"||These graphs are not provided by the conduit, so phpDiveLog will have to generate them if you want them (which means,
||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.|
||"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.|
||FALSE||This setting decides whether to use transparent background for the graphs (TRUE) or not (FALSE).|
||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.|
||10||Temperature intervals for the corresponding statistics graph. You may set this to either 5 or 10.|
||10||Time interval (in minutes) for the Dives by Duration graph. Set this to either 10 or 20 (30 should also work).|
||5||Interval (in meters) for the Dives by Depth graph. Valid settings are 5, 10, and 20.|
Data Transfer Settings
||"/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.|
||"/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.
||"date"||sort||Sorting the logbook (dive list)|
||"desc"||order||Ordering the logbook|
||"location"||sort||Sorting the site list|
||"asc"||order||Ordering the site list|
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
*.rpm packages. (Note: the packages in the repositories have not been updated for a while, and probably won't be updated soon).
||"/usr/share/tcpdf/"||Where the TCPDF files are installed. If you installed TCPDF from our repository, you don't need to touch this.|
||"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
||"P"||Orientation of the page:
||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)|
||5||Space on the side opposite to the gutter|
||"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.|
||TRUE||Would you like to have some photos included with your logbook pages (if there are dive photos connected)? Setting this to
||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.|
||1900||To make sure the notes fit in the template, they will be truncated when exceeding this value|
||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|
||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
Configuration Overrides by Divers
||"explicit"||How to tell which settings may be overridden by the divers
||(depends on version)||here we define which configuration variables may be overridden by the
||(depends on version)||which configuration variables may not be overridden when
||"EW"||What information shall be logged. This can be a combination of events (chose the bold letter):
||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.|
||1||Whether to store error messages to the web servers
These settings are intended to handle search engine crawlers, and especially prevent their recursion through too many levels plus limit their visits, if possible:
||"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.|
||"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.|
||"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.|
||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.|
||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.|
||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 :)|
||"inc/emoticons.csv"||Emoticon definition file (see Emoticons). Comment out if you don't want to have emoticons to be used.|
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.
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
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.
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/*/profilesfor dynamically created graph images
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.
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.
With only one diver, you probably will set the
$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.
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