Differences

This shows you the differences between two versions of the page.

--- build:wiki [2007/07/25 14:25]
206.197.251.70 Add a couple ideas to TODO. (CMB)
+++ build:wiki [2011/01/12 16:39] (current)
SLUUG Administration Upgrade to DokuWiki 2010-11-07. (CMB)
@@ Line 1: / Line 1: @@
 ====== DokuWiki ======
-These instructions detail how to install [[http://wiki.splitbrain.org/wiki:dokuwiki | DokuWiki]] (2005-09-22) on our Debian 3.1 system.
+These instructions detail how to install [[http://wiki.splitbrain.org/wiki:dokuwiki | DokuWiki]] on our Debian GNU/Linux system. We're currently running the 2010-11-07 version of DokuWiki.
 ===== Requirements =====
   * Apache
-  * PHP (currently 4.3.x only)
+  * PHP (4.3.x or 5.x)
     * PHP's [[http://de2.php.net/manual/en/ref.image.php|GD]] extension with [[http://www.boutell.com/gd/|libGD 2]] is recommended but not needed
@@ Line 13: / Line 13: @@
 Download and unpack the program:
 <code rootshell>
+export VERSION=2005-09-22
 cd /home/web/wiki.sluug.org/
-wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2005-09-22.tgz
+wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-$VERSION.tgz
-tar xfz dokuwiki-2005-09-22.tgz
+tar xfz dokuwiki-$VERSION.tgz
-mv dokuwiki-2005-09-22/* dokuwiki-2005-09-22/.ht* .
+rm dokuwiki-$VERSION.tgz
-rmdir dokuwiki-2005-09-22/
+rm -f public
-rm dokuwiki-2005-09-22.tgz
+ln -s dokuwiki-$VERSION public
+cd public
 touch data/changes.log
 chown -R www-data:www-data * .ht*
@@ Line 51: / Line 53: @@
 </code>
-Edit the conf/local.php	file to look like this (make sure it doesn't have any blank lines outside the PHP tags):
+Edit the ''conf/local.php'' file to look like this (make sure it doesn't have any blank lines outside the PHP tags):
 <code php>
 <?php
@@ Line 65: / Line 67: @@
 $conf['usewordblock'] = 0;         // Don't block posts using "banned" words.
 $conf['mailguard'] = 'visible';    // Use "name [at] domain [dot] com" format to display email addresses.
+$conf['typography'] = 0;           // Don't convert quotes to fancy version.
+$conf['license'] = 'cc-by-sa';     // License of all content. See conf/license.php and conf/license.local.php for choices.
+$conf['showuseras'] = 'username';  // Show users' full names, no email addresses or login names.
 #$conf['useacl'] = 1;               // TODO: Have to create users (manually).
 #$conf['authtype'] = 'plain';       // User IDs are stored in a flat file.
 #$conf['openregister'] = 1;         // Users may register themselves.
 #$conf['defaultgroup'] = 'user';    // Users registering themselves belong to this group.
-?>
+</code>
+Deactivate the automatic conversion of certain character combinations into different symbols since this destroys the ability to cut/paste commands and sample configuration data from the documentation.  For example, DokuWiki was converting ''--inet=1'' into ''&ndash;inet='' which resulted in a single dash when cut/pasted from the browser to another window, with the copied command failing.
+<code rootshell>
+mv conf/entities.conf conf/entities.conf.out
 </code>
@@ Line 80: / Line 89: @@
 </code>
-Create the backup script in /etc/cron.daily/backup-dokuwiki:
+Create the backup script in ''/etc/cron.daily/backup-dokuwiki'':
 <code bash>
 #!/bin/sh
@@ Line 88: / Line 97: @@
 EXCLUDE='data/cache/*'
 INCLUDE='data/ conf/'
-WIKIDIR=/home/web/wiki.sluug.org/
+WIKIDIR=/home/web/wiki.sluug.org/public
 tar cfz $BACKUPDIR/wikidata-$DATE.tgz -C $WIKIDIR --exclude="$EXCLUDE" $INCLUDE
@@ Line 98: / Line 107: @@
 </code>
-Run the script to test that it works, and saves a file in /var/backups/web/. Run 'tar tfz' on the resulting backup file to make sure it contains files in the data and conf directories.
+Run the script to test that it works, and saves a file in ''/var/backups/web/''. Run ''tar tfz'' on the resulting backup file to make sure it contains files in the ''data'' and ''conf'' directories.
-TODO: Copy the files in /var/backups off the server.
+TODO: Copy the files in ''/var/backups'' off the server.
 ===== Testing =====
@@ Line 109: / Line 118: @@
 Make sure history feature ("Old revisions") works.
-===== Patches =====
-On January 7, 2006, the wiki started getting the following error intermittently:
-<code>
-Fatal error: session_start(): Failed to initialize storage module: user
-(path: /var/lib/php4) in /home/web/wiki.sluug.org/inc/init.php on line 50
-</code>
-Searching Google found this to be a long-standing unresolved [[http://bugs.php.net/bug.php?id=25876 | PHP bug]]. The following patch was added, per some suggestions on the bug-discussion page. It seems to have resolved the issue.
-<code>
---- inc/init.php.ORIG   2005-09-22 12:21:13.000000000 -0500
-+++ inc/init.php        2006-01-08 01:18:51.000000000 -0600
-@@ -45,6 +45,14 @@
-   // make session rewrites XHTML compliant
-   @ini_set('arg_separator.output', '&amp;');
-+// Possible work-arounds for error we've experienced:
-+//    Fatal error: session_start(): Failed to initialize storage module: user
-+//    (path: /var/lib/php4) in /home/web/wiki.sluug.org/inc/init.php on line 50
-+// Error is detailed at http://bugs.php.net/bug.php?id=25876
-+// Added 2006-01-08 by Craig Buchek.
-+session_module_name("files");
-+ini_set("session.save_handler", "files");
-+
-   // init session
-   session_name("DokuWiki");
-   if (!headers_sent()) session_start();
-</code>
 ===== Upgrading =====
-Here are the steps taken to upgrade to version 2007-06-26b.
+Here are the steps taken to upgrade to version 2010-11-07.
-First we create a backup of the existing site.
+First, read the [[http://www.dokuwiki.org/changes | changes made in the new release]]. Make sure you follow any directions specific to the new release.
-<code rootshell>
-cd /home/web
+Then we create a full backup of the existing site.
-tar cfz /var/backups/web/wiki.sluug.org.BACKUP-`date +%Y%m%d`.tgz wiki.sluug.org
+<code bash>
+cd /home/web/wiki.sluug.org
+export OLD_VERSION=2009-12-25
+sudo tar cfz /var/backups/web/wiki.sluug.org.BACKUP-`date +%Y%m%d`.tgz dokuwiki-$OLD_VERSION
 </code>
 Download and unpack the new version.
-<code rootshell>
+<code bash>
-export VERSION=2007-06-26b
+cd /home/web/wiki.sluug.org
+export VERSION=2010-11-07
 wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-$VERSION.tgz
 tar xfz dokuwiki-$VERSION.tgz
@@ Line 159: / Line 141: @@
 </code>
-Read through ''dokuwiki-$VERSION/.htaccess'' to look for anything new.
+Read through ''dokuwiki-$VERSION/.htaccess.dist'' to look for anything new. Make any necessary changes.
 <code bash>
-diff -u wiki.sluug.org/.htaccess dokuwiki-$VERSION/.htaccess | less
+diff -u dokuwiki-$OLD_VERSION/.htaccess dokuwiki-$VERSION/.htaccess.dist | less
 </code>
-Read through the ''dokuwiki-$VERSION/conf/dokuwiki.php'' file to look for any new config options.
+Read through the ''dokuwiki-$VERSION/conf/dokuwiki.php'' file to look for any new config options. Make any necessary changes to ''conf/local.php'' in the OLD directory.
 <code bash>
-diff -u wiki.sluug.org/conf/dokuwiki.php dokuwiki-$VERSION/conf/dokuwiki.php | less
+diff -u dokuwiki-$OLD_VERSION/conf/dokuwiki.php dokuwiki-$VERSION/conf/dokuwiki.php | less
 </code>
-Double-check to see if there are any patches in the old version of DokuWiki. If so, you'll probably have to manually apply the patches to the new version. (Check to ensure they're still needed first though.) In this case, I manually added the patch listed above.
+Double-check to see if there are any patches in the old version of DokuWiki. If so, you'll probably have to manually apply the patches to the new version. (Check to ensure they're still needed first though.)
 <code bash>
-find wiki.sluug.org -name '*.ORIG*'
+find dokuwiki-$OLD_VERSION -name '*.ORIG*'
 </code>
-Delete the old caches, since we don't need it, and the formats may have changed between versions. We can also use the new help pages (in the wiki namespace), so we can delete them from the old site.
+Delete the old cache and index, since they can be regenerated, and the formats may have changed between versions. We can also use the new help pages (in the wiki namespace), so we can delete them from the old site.
-<code rootshell>
+<code bash>
-rm wiki.sluug.org/data/cache/* -rf
+sudo rm dokuwiki-$OLD_VERSION/data/cache/* -rf
-rm wiki.sluug.org/data/pages/wiki -rf
+sudo rm dokuwiki-$OLD_VERSION/data/index/* -rf
+sudo rm dokuwiki-$OLD_VERSION/data/pages/wiki -rf
 </code>
 Copy all the configuration info and data over from the old site to the new site.
-<code rootshell>
+<code bash>
-cp -f wiki.sluug.org/conf/{local.php,acl.auth.php,users.auth.php} dokuwiki-$VERSION/conf/
+cp -f dokuwiki-$OLD_VERSION/conf/{*local.php,acl.auth.php,users.auth.php} dokuwiki-$VERSION/conf/
-cp -f wiki.sluug.org/.htaccess dokuwiki-$VERSION/
+cp -f dokuwiki-$OLD_VERSION/.htaccess dokuwiki-$VERSION/
-cp -a wiki.sluug.org/data/* dokuwiki-$VERSION/data/
+cp -a dokuwiki-$OLD_VERSION/data/* dokuwiki-$VERSION/data/
+</code>
+Get rid of the files that we don't need.
+<code bash>
+mv dokuwiki-$VERSION/conf/entities.conf dokuwiki-$VERSION/conf/entities.conf.dist
+rm dokuwiki-$VERSION/{install,index}.php
 </code>
@@ Line 190: / Line 179: @@
 Re-create the sitemap file.
-<code rootshell>
+<code bash>
 touch dokuwiki-$VERSION/sitemap.xml.gz
 </code>
-Correct the ownership so that the web server can write to where it needs to.
+Re-index the site.
-<code rootshell>
+<code bash>
-chown -R www-data:www-data dokuwiki-$VERSION
+php dokuwiki-$VERSION/bin/indexer.php -c
+</code>
+Correct the ownership and permissions so that the web server can write to where it needs to, and so admins can also write files within the directory.
+<code bash>
+sudo chown -R www-data:www-data dokuwiki-$VERSION
+sudo chmod -R g+w dokuwiki-$VERSION
 </code>
 Switch over to the new version.
-<code rootshell>
+<code bash>
-mv wiki.sluug.org wiki.sluug.org.OLD
+rm public
-mv dokuwiki-$VERSION wiki.sluug.org
+ln -s dokuwiki-$VERSION public
 </code>
-Test the site. Make sure you can browse to a few different pages. Also make sure you can edit and save a page. Once you're comfortable that the upgrade went OK, you can delete the ''wiki.sluug.org.OLD'' directory.
+Test the site. Make sure you can browse to a few different pages. Also make sure you can edit and save a page. Check out the search feature, backlinks, and old revisions.
-===== TODO: Enable ACLs and User Accounts =====
+Once you're comfortable that the upgrade went OK, you can delete the directory for the previous version of DokuWiki.
-Create the conf/users.auth file:
+<code bash>
-<code rootshell>
+rm -rf dokuwiki-$OLD_VERSION
-touch conf/users.auth
-chown www-data:www-data conf/users.auth
-chmod 440 conf/users.auth
 </code>
-Add an admin account in the file (replace $WIKI_ADMIN_PWD with real password):
+===== Enable ACLs and User Accounts =====
-  # echo "admin:`echo -n '$WIKI_ADMIN_PWD' | md5sum | awk '{print $1;}'`:Administrator:webmaster@sluug.org:admin,users" >> conf/users.auth
+==== This is a minimal implementation with a single account ====
+=== The sole purpose is to reduce defacement and overhead from recovery. ===
-Create the conf/acl.auth file:
+Go to the DokuWiki configuration directory
-<code rootshell>
+<code>
-cp conf/acl.auth.dist conf/acl.auth
+cd /home/web/wiki.sluug.org/public/conf
-chown www-data:www-data conf/acl.auth
-chmod 440 conf/acl.auth
 </code>
-Edit the conf/acl.auth file to look something look this:
+Install the skeleton authorization files
-<code configfile>
+<code>
-*               @admin  255
+cp -ip users.auth.php.dist users.auth.php
-*               @ALL    7
+cp -ip acl.auth.php.dist acl.auth.php
-private:*       @admin  255
-private:*       @ALL    0
-readonly:*      @admin  255
-readonly:*      @ALL    1
 </code>
+Create a backup of the main config file
+<code>
+cp -ip local.php local.php.090219
+</code>
-===== TODO =====
+Edit local.php using your favorite editor to uncomment the useacl line:
+<code>
+$conf['useacl']       = 1;        // Enable Access Control List authorization
+</code>
-Consider using subdirectories of /home/web/wiki.sluug.org/, so we can keep old versions and the current version inside of that directory.
+Create a new account using your web browser:
-Copy the files in /var/backups off the server. Delete older versions, or at least create a subdirectory structure.
+  - Point the web browser at http://wiki.sluug.org/
+  - Select the "Login" button at the bottom of the page.
+  - Select the "Register" link.
+  - Fill in
+    - Username:  discuss
+    - Real name: SLUUG Administration
+    - E-mail:    (your e-mail address)
+  - Select the "Register" button.  You should end up at the login page again.
+  - Read the mail sent to you and login using the generated password.
+  - At the bottom of the page, select the "Update Profile" button.
+  - Change these fields:
+    - E-mail:        root@mail.sluug.org
+    - New passsword: (The password for the discuss mailing list archive)
+  - Select the "Save" button.
-Accounts/ACLs. [[http://wiki.splitbrain.org/wiki:acl | See documentation]]. Set admin's password.
+Edit local.php using your favorite editor to add this line:
+<code>
+$conf['disableactions'] = 'register';   // Users can't register themselves
+</code>
+Test security using your web browser:
+  - Select the "Logout" button.
+  - Tried editing a page without being logged in, but it let me.
+  - Tried editing a page after closing and restarting the browser, but it let me.
+Edit acl.auth.php using your favorite editor to:
+  - Change the authority of the "ALL" group from "8" to "1".
+  - Create a new line in the same format, giving user "discuss" "16" level authority.
+<code>
+*               discuss    16
+</code>
+An attempt to edit the same page (still displayed from the earlier test)
+still displays the source, but now says that update is not allowed.
+Refreshing the page, it no longer has the "Edit" buttons.
+Test for an authenticated user:
+  - Use the "Login" button, enter the username and password from above.
+  - The Edit buttons are now displayed and able to update this page.
+For more information, see the
+[[http://wiki.splitbrain.org/wiki:acl | ACL documentation]].
+===== TODO =====
+Copy the files in /var/backups off the server. Delete older versions, or at least create a subdirectory structure.
 Turn on wordblock to ban edits with certain words (to prevent spamming and profanity)?
@@ Line 261: / Line 301: @@
 ===== Credits =====
-Initially installed, configured, and documented by Craig Buchek, 2005-09-10. Updated to newer versions on 2005-11-26 and 2007-05-09.
+Initially installed, configured, and documented by Craig Buchek, 2005-09-10.
+Updated to newer versions on 2005-11-26, 2007-05-09, 2008-06-11, 2009-02-19, 2010-01-08.

SLUUG Wiki

User Tools

Site Tools

Differences

Page Tools