Item13504: Document Page cache dependencies

And add some notes on how to configure MySQL and PostgreSQL. This needs some review by someone who knows mysql and postgresql.
foswiki · Jul 25, 2015 · 77f5b4a · 77f5b4a
1 parent cd9ebdd
commit 77f5b4a
Show file tree

Hide file tree

Showing 3 changed files with 83 additions and 6 deletions.
diff --git a/core/data/System/PageCaching.txt b/core/data/System/PageCaching.txt
@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" date="1434484983" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1437799448" format="1.1" version="1"}%
 %META:TOPICPARENT{name="AdminDocumentationCategory"}%
 ---+!! Page Caching
 How to get the best from HTML Caching.
@@ -83,9 +83,9 @@ Firstly, the main page will be cached with asynchronously computed fragments tak
 the main page will have less dependencies on additional content and is less likely to be invalidated from
 the page cache.
 
-Sencond, each fragment requested via an ajax call and inserted into the main page dynamically is computed
+Second, each fragment requested via an ajax call and inserted into the main page dynamically is computed
 and cached separately, each with its own set of dependencies. So when one fragment's dependency is fired (one of
-its ingredience has been updated), then only this single fragment and not the complete page nor the other fragments
+its ingredients has been updated), then only this single fragment and not the complete page nor the other fragments
 need recomputation.
 
 The general pattern for asynchronously loaded page fragments looks like this:
@@ -206,7 +206,8 @@ At the same time these expressions are the candidates that benefit the most from
 are the most expensive ones.
 
 ---+++ Caching REST results (Developers)
-If a function called to service a =rest= script returns it's result using =return=, then the result will be cached. If the function returns an empty result or undef, then the function is totally responsible for its own output, and there is no caching.
+If a function called to service a =rest= script returns it's result using =return=, then the result will be cached.
+If the function returns an empty result or undef, then the function is totally responsible for its own output, and there is no caching.
 
 ---++ Configuring the Cache
 ---+++ Choosing a database engine
@@ -216,6 +217,66 @@ pages in a database. For larger sites in production use, you should choose eithe
 or =Foswiki::PageCache::DBI::PostgreSQL=. For smaller sites and personal wikis, =Foswiki::PageCache::DBI::SQLite=
 is approriate as well.
 
+---++++ SQLite
+
+SQLite can be used with no special configuration.   The page cache will be
+indexed by =working/sqllite.db=, and topics are cached in the =working/cache=
+directory.  There is one configuration parameter that can be changed:
+   * ={Cache}{DBI}{SQLite}{Filename} = '$Foswiki::cfg{WorkingDir}/sqlite.db';=
+
+---++++ !MySQL
+
+Before Foswiki is able to use !MySQL for caching, several conditions must be met:
+   * The mysql server and the perl DBI / DBD modules for !MySQL must be installed.
+   * A database, must be created.
+   * The user needs to be created, and appropriate permissions granted.  <verbatim>
+   foswikihost: ~ $ mysql -u root -p
+   Enter password:  ........
+   Welcome to the MySQL monitor.  Commands end with ; or \g.
+
+   mysql> create database foswiki;
+   Query OK, 1 row affected (0.00 sec)
+
+   mysql>  grant usage on *.* to foswiki@localhost identified by 'foswikipass';
+   Query OK, 0 rows affected (0.00 sec)
+
+   mysql> grant all privileges on foswiki.* to foswiki@localhost ;
+   Query OK, 0 rows affected (0.00 sec)
+   </verbatim>
+   * Foswiki must be configured with the database, user and password information.  For example:
+      * ={Cache}{DBI}{MySQL}{Database} = 'foswiki';=
+      * ={Cache}{DBI}{MySQL}{Host} = 'localhost';=
+      * ={Cache}{DBI}{MySQL}{Password} = 'foswikipass';=
+      * ={Cache}{DBI}{MySQL}{Port} = '';=
+      * ={Cache}{DBI}{MySQL}{Username} = 'foswiki';=
+
+---++++ !PostgreSQL
+
+Before Foswiki is able to use !PostgreSQL for caching, several conditions must be met:
+   * The !PostgreSQL server and the perl DBI / DBD modules for !PostgreSQL must be installed.
+   * A database, must be created.
+   * The user needs to be created, and appropriate permissions granted.  <verbatim>
+   user@server: sudo su -- postgres
+   postgres@server:/root$ createuser foswiki --pwprompt
+
+   postgres@server:/root$ psql
+   psql (9.4.4)
+   Type "help" for help.
+
+   postgres=# alter user foswiki with password 'foswikipass';
+   ALTER ROLE
+   postgres=# create database foswiki;
+   CREATE DATABASE
+
+   \q
+   </verbatim>
+   * Foswiki must be configured with the database, user and password information.  For example:
+      * ={Cache}{DBI}{PostgreSQL}{Database} = 'foswiki';=
+      * ={Cache}{DBI}{PostgreSQL}{Host} = 'localhost';=
+      * ={Cache}{DBI}{PostgreSQL}{Password} = 'foswikipass';=
+      * ={Cache}{DBI}{PostgreSQL}{Port} = '';=
+      * ={Cache}{DBI}{PostgreSQL}{Username} = 'foswiki';=
+
 See the <a href="%SCRIPTURLPATH{"view"}%/%SYSTEMWEB%/PerlDoc?module=Foswiki::PageCache">Foswiki::PageCache</a>
 documentation for more detailed information.
 

diff --git a/core/data/System/SystemRequirements.txt b/core/data/System/SystemRequirements.txt
@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" date="1436234283" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1437799448" format="1.1" version="1"}%
 %META:TOPICPARENT{name="AdminDocumentationCategory"}%
 ---+ System Requirements
 
@@ -47,6 +47,10 @@ Install apache and rcs: ==apt-get install apache2 rcs==
 | Authen::SASL | =libauthen-sasl-perl= | |
 | CGI | =libcgi-pm-perl= | |
 | CGI::Session | =libcgi-session-perl= | |
+| DBI | =libdbi-perl= | Used for the Foswiki Page cache |
+| DBD::mysql | =libdbd-mysql-perl= | Used for !MySQL based Page Cache |
+| DBD::Pg | =libdbd-pg-perl= | Used for !PostgreSQL based Page Cache |
+| DBD::SQLite | =libdbd-sqlite3-perl= | Used for SQLite based Page Cache |
 | Crypt::PasswdMD5 | =libcrypt-passwdmd5-perl= | |
 | Digest::SHA | =libdigest-sha-perl= | *First shipped in perl 5.9.3 |
 | Encode | =libencode-perl= | |
@@ -90,6 +94,10 @@ Install apache2, rcs, and perl-CPAN
 | CGI | =perl-CGI=  | |
 | CGI::Session | =perl-CGI-Session= | |
 | Crypt::PasswdMD5 | =perl-Crypt-PasswdMD5= | |
+| DBI | | Used for the Foswiki Page cache |
+| DBD::mysql | | Used for !MySQL based Page Cache |
+| DBD::Pg | | Used for !PostgreSQL based Page Cache |
+| DBD::SQLite | | Used for SQLite based Page Cache |
 | Digest::SHA | =perl-Digest-SHA= | *First shipped in perl 5.9.3 |
 | Encode | =perl-Encode=  | |
 | Error | =perl-Error= | |
@@ -126,6 +134,10 @@ Install =www-servers/apache=, =dev-vcs/rcs=, and =dev-lang/perl=
 | CGI | =perl-core/CGI= | |
 | CGI::Session | =dev-perl/CGI-Session= | |
 | Crypt::PasswdMD5 | =dev-perl/Crypt-PasswdMD5= | |
+| DBI | | Optional - Used for the Foswiki Page cache |
+| DBD::mysql | | Optional - Used for MySQL based Page Cache |
+| DBD::Pg | | Optional - Used for PostgreSQL based Page Cache |
+| DBD::SQLite | | Optional - Used for SQLite based Page Cache |
 | Digest::SHA | =perl-core/Digest-SHA= | Included with perl |
 | Error | =dev-perl/Error= | |
 | Encode | =perl-core/Encode= | |
@@ -156,7 +168,7 @@ If run as root, the modules will be installed in the System perl.   Otherwise th
 
 <verbatim>
 curl -L http://cpanmin.us | perl - App::cpanminus    (optional - install cpanminus if not available )
-cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 Digest::SHA Error Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext::Lexicon Locale::Msgfmt LWP version URI
+cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 DBI DBD::mysql DBD::Pg DBD::SQLite Digest::SHA Error Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext::Lexicon Locale::Msgfmt LWP version URI
 </verbatim>
 
 If you want to install the dependendencies into a specified location, add the ="-l"= option to cpanm, and add the lib path to =bin/LocalLib.cfg=.   The dependencies will be installed under the specified location, in the =lib/perl5= subdirectory.

diff --git a/core/lib/Foswiki/Contrib/core/DEPENDENCIES b/core/lib/Foswiki/Contrib/core/DEPENDENCIES
@@ -5,6 +5,10 @@ Authen::SASL,>=2.00,cpan,Optional, required for sending mail with Net::SMTP when
 CGI,>=3.15,cpan,Required, for base Foswiki (Versions 2.89, 3.37, 3.43, 3.47 and 4.11-13 should be avoided for I18N. Most version from 3.15 and onwards should work. Note: As of perl 5.19.7, CGI is no longer shipped with perl core and must be installed using CPAN.)
 CGI::Cookie,>=1.24,cpan,Required, Installs as part of CGI.
 CGI::Session,>=4.30,cpan,Required, for configure and Sessions support, available from the CPAN archive.
+DBI,>=0,cpan,Optional, required for Foswiki Page Caching
+DBD::mysql,>=0,cpan,Optional, used for Foswiki Page Cache using MySQL
+DBD::Pg,>=0,cpan,Optional, used for Foswiki Page Cache using PostgreSQL
+DBD::SQLite,>=0,cpan,Optional, used for the Foswiki Page Cache and SQLite
 Digest::SHA,>=0,cpan,Optional, may be required for password encryption.
 Crypt::Eksblowfish::Bcrypt,>0,cpan,Optional, only needed if Foswiki passwords should be encoded using bcrypt.
 Crypt::PasswdMD5,>=0,cpan,Required, for admin password hash and .htpasswd encoding.