Installing Foswiki 1.1.9 on debian-based Linux

The set of instructions required to make Foswiki run on debian-based systems is fairly complex. The developers were kind and helped me through the installation process, but I want to document the pitfalls here.

We are installing Foswiki 1.1.9 (the most-recent version when writing this post) on debian 7.5 (wheezy). Foswiki will be running with FastCGI in perl 5.14.2 (the approach with mod_fcgid we will use is recommended by the developers). I have also tested it for xubuntu 14.04. Be aware that those steps are already documented in the provided installation guide. I am using a root shell. In xubuntu you can obtain one using sudo -i.

  1. Download Foswiki and uncompress it.

    wget -c "http://sourceforge.net/projects/foswiki/files/foswiki/1.1.9/Foswiki-1.1.9.tgz"
    tar -zvxf Foswiki-1.1.9.tgz foswiki
  2. Move it to /var/www which is the content directory for the webserver. If everything is fine, you will find a readme in /var/www/foswiki:

    mv Foswiki-1.1.9 /var/www/foswiki
    ls /var/www/foswiki/readme*  # must return a path
  3. Now let us install all required debian packages. The cpan commandline utility should already be available.

    sudo apt-get install apache2 libapache2-mod-fcgid apache2-utils
  4. Open the installation guide to make sure you don’t miss any settings for your installation.

    cat /var/www/foswiki/INSTALL.html
  5. Set the file permissions and owner. For now, I will just assign the webserver as owner:

    sudo chown -R www-data:www-data /var/www/foswiki
  6. Visiting http://localhost/ should already return the Apache default webpage.

  7. Now we will disable the default site and configure the Apache webserver for foswiki. We open /etc/apache2/sites-available/default and put a hash “#” at the beginning of every line. You can use :%s/^/#/g in vim, but you have to install vim first.

  8. Now we create our foswiki apache configuration. Visit the ApacheConfigGenerator can create your own configuration file. FYI, I am not using htaccess files and apache configuration files only. Furthermore I am using short URLs and FastCGI with mod_fcgid. We store this file at /etc/apache2/sites-available/foswiki.

  9. We have to keep sites-available and sites-enabled synchronized. We create a soft link:

    ln -s /etc/apache2/sites-available/foswiki /etc/apache2/sites-enabled/foswiki
  10. From this point on our configuration will differ. However, I will post my Apache configuration here for reference.

  11. In our apache configuration, we use a htpasswd file. We have to create it. Depending on your htpasswd version, option -B (bcrypt) or -s (SHA) might be appropriate. This creates a Foswiki user admin.

    # This line appears in my apache config
    #   AuthUserFile /var/www/foswiki/data/.htpasswd
    htpasswd -s -c /var/www/gdi/data/.htpasswd admin
  12. We now try to use the new configuration file. Apparently Apache is not happy:

    # service apache2 restart
    Syntax error on line 33 of /etc/apache2/sites-enabled/gdi-foswiki:
    Invalid command 'RewriteEngine', perhaps misspelled or defined by a module not included in the server configuration
    Action 'configtest' failed.
    The Apache error log may have more information.
     failed!

    Foswiki uses the Apache mod_rewrite module to adjust its URLs. We have to enable it

  13. a2enmod rewrite cgid fgcid

    Wait… we are using FastCGI. Why do we need cgid (the CGI module)? The configure script provides us the installation and is run with CGI. Foswiki itself will run with FastCGI later on.

  14. Finally you also need to install the CPAN module FCGI to make FastCGI work later on. This requires the gcc and build-essential.

    apt-get install gcc build-essential
    cpan install FCGI

    The commands

    perl -e 'use CGI'
    perl -e 'use FCGI'

    must succeed (ie. return nothing with exit code 0)

  15. Let’s restart apache again.

    # service apache2 start
    [ ok ] Starting web server: apache2.

    If you receive any port binding error like

    # service apache2 start
    [....] Starting web server: apache2(98)Address already in use: make_sock: could not bind to address [::]:80
    . ok

    your Apache tries to bind to port 80 twice. In other words there is more than 1 line in /etc/apache2 containing the directive Listen 80. Remove all but one in this case.

  16. Now visit localhost/foswiki/bin/configure to run the configure script.

  17. Configure the “General Path Settings”. The default settings work for me.

  18. Coming back to this page should give you plenty more settings. I highly recommend the following settings:

    • In “Store” use “Foswiki::Store::RcsLite” for {Store}{Implementation}
    • In “Internationalisation” use “en_US.UTF-8” (or any appropriate one for your country) for {Site}{Locale}
    • In “Internationalisation” use “utf-8” for {Site}{Charset}
  19. Now you have to enable FastCGIEngineContrib. Go to extensions tab in the configure script and select “Install, Update and Remove Extensions”. You have to select “install” for “FastCGIEngineContrib”. After entering your password, you will read “Installation of FastCGIEngineContrib and dependencies finished” if everything went fine.

  20. Well done! Your Foswiki is running at localhost! 🙂

GeorgeClark renewed his proposal to make FastCGIEngineContrib a core extension so that RcsLite is not required to install it. So in Foswiki releases higher Foswiki 1.1.9 the corresponding steps might not be necessary.

And btw, if you experience any problems, join IRC #foswiki at freenode. They are really nice guys 🙂

Installing Foswiki 1.1.9 on debian-based Linux