.. meta::
  :navigation.order: 2
  :navigation.name: Installation

Installation
============

Requirements for Unix/Linux or Max OS X
---------------------------------------

1. You need a standard GNU development environment with
   
   - C compiler (for example the GNU C Compiler gcc)
     
     Depending on your distribution, several development packages
     might be needed to provide a fully functional C development
     environment.
   
   Note for developers: if you want to regenerate the .pot template
   from the source files, you will need xgettext with Python support.
   This is available in gettext >= 0.12.

2. Python >= 2.4 from http://www.python.org/ with zlib support

3. runit from http://smarden.org/runit/

4. *Optional (used by ImageSize and ImageReducer module)*
   Python Imaging Library (PIL) from
   http://www.pythonware.com/products/pil/

5. *Optional (used for NTLM authentication)*
   Python Crypto Module from
   http://www.amk.ca/python/code/crypto.html

6. *Optional (used for SSL connections)*
   OpenSSL and PyOpenSSL from
   http://www.openssl.org/ and
   http://pyopenssl.sourceforge.net/

7. *Optional (used by VirusFilter module)*
   ClamAv from
   http://www.clamav.net/

8. *Optional (speedup for i386 compatible PCs)*
   Psyco from
   http://psyco.sourceforge.net/
   [http://osdn.dl.sourceforge.net/sourceforge/psyco/psyco-1.4-src.tar.gz]

Requirements for Windows:
-------------------------
Direct download links are in brackets.

1. Install Python >= 2.4 from http://www.python.org/
   [http://www.python.org/ftp/python/2.4.1/python-2.4.1.msi]

2. Install Python for Windows Extensions from
   http://starship.python.net/crew/mhammond/
   [http://osdn.dl.sourceforge.net/sourceforge/pywin32/pywin32-204.win32-py2.4.exe]

3. *Only needed if you compile from source:*
   install the MinGW suite from http://mingw.sourceforge.net/.
   Be sure to install in the given order:
   
   a) MingGW
      [http://osdn.dl.sourceforge.net/sourceforge/mingw/MinGW-4.1.1.exe]
   b) MSYS
      [http://osdn.dl.sourceforge.net/sourceforge/mingw/MSYS-1.0.10.exe]
   
4. *Optional (used by ImageSize and ImageReducer module)*
   Install Python Imaging Library (PIL) from
   http://www.pythonware.com/products/pil/
   [http://effbot.org/downloads/PIL-1.1.5.win32-py2.4.exe]

5. *Optional (used for NTLM authentication)*
   Download Python Crypto Module from
   http://www.amk.ca/python/code/crypto.html
   [http://webcleaner.sourceforge.net/pycrypto-2.0.1.win32-py2.4.exe]

6. *Optional (used for SSL connections)*
   Install OpenSSL and PyOpenSSL for Windows from
   http://www.shininglightpro.com/products/Win32OpenSSL.html
   [http://www.shininglightpro.com/download/Win32OpenSSL-v0.9.8.exe]
   and
   http://pyopenssl.sourceforge.net/
   [http://webcleaner.sourceforge.net/pyOpenSSL-0.6.win32-py2.4.exe]

7. *Optional (used by VirusFilter module)*
   ClamAv from
   http://www.sosdg.org/clamav-win32/index.php
   [http://www.sosdg.org/clamav-win32/clamav-devel.exe]

8. *Optional (speedup for i386 compatible PCs)*
   Psyco from
   http://psyco.sourceforge.net/
   [http://osdn.dl.sourceforge.net/sourceforge/psyco/psyco-1.4.win32-py2.4.exe]

Setup for Unix/Linux:
---------------------

1. Install check
   
   Be sure to have installed all required Unix/Linux software listed above.

2. Compilation
   
   Run ``./configure && make`` to compile the included C libraries.
   Run ``python setup.py build`` to compile the Python files.
   For help about the setup.py script options, run
   ``python setup.py --help``.
   The CC environment variable is checked before compilation, so you can
   change the default C compiler with ``export CC=myccompiler``.
   If you work from CVS, you must run ``./autogen.sh`` first to generate the
   configure and Makefile files.

3.
   a) Installation as root
      
      Run ``su -c 'python setup.py install'`` to install the proxy.
      Run ``su -c 'webcleaner-certificates install'`` to install the
      certificates.
      Run ``su -c 'make installservice'`` to install the runit service.
   
   b) Installation as a normal user
      
      Run ``python setup.py install --home $HOME``. Note that you have
      to adjust your PATH and PYTHONPATH environment variables, eg. by
      adding the commands ``export PYTHONPATH=$HOME/lib/python`` and
      ``export PATH=$PATH:$HOME/bin`` to your shell configuration
      file.
      
      For more information look at the `Modifying Python's search path`_
      documentation.
      
      .. _Modifying Python's search path:
         http://docs.python.org/inst/search-path.html#SECTION000410000000000000000
      
      Now run ``webcleaner-certificates install`` to install the SSL
      certificates.
      After that read the `runsvdir(8)`_ documentation on how to setup a
      local runit service.
      
      .. _runsvdir(8):
         http://smarden.org/runit/runsvdir.8.html
   
   If you downloaded Psyco please read the `psyco installation docs`_.
   
   .. _psyco installation docs:
      http://psyco.sourceforge.net/psycoguide/node2.html

4. Enjoy
   
   WebCleaner is now installed as a runit service and will start
   automatically in 5 seconds.
   See the `main page`_ on how to configure the proxy filters.
   
   .. _main page:
      index.html

Setup for Windows - the binary .exe installer:
----------------------------------------------

1. Install check
   
   Be sure to have installed all required windows software listed above.

2. Execute the ``webcleaner-x.xx.win32-py2.4.exe`` file and follow
   the instructions.

Setup for Windows - compiling from source:
------------------------------------------

1. Install check
   
   Be sure to have installed all required windows software listed above.

2. Preparing Python for the MinGW compiler
   
   Search the file python24.dll in your windows folder.
   After you found it, launch MSYS. Change into the windows folder,
   for example ``% cd c:\winnt\system32``. Then execute
   ``% pexports python24.dll > python24.def``.
   Then use the dlltool with
   ``% dlltool --dllname python24.dll --def python24.def --output-lib
   libpython24.a``.
   The resulting library has to be placed in the same directory as
   python24.lib. (Should be the libs directory under your Python installation
   directory, for example ``c:\Python24\Libs\``.)

3. Compile the JavaScript library
   
   Copy the webcleaner-X.Y.tar.gz into your MSYS home directory,
   which is usually under c:\\msys\\1.0\\home\\user\\.
   Launch MSYS and extract the tarball with
   ``% tar xzvf webcleaner-X.Y.tar.gz``.
   Now change into the generated directory with
   ``% cd webcleaner-X.Y`` and configure and compile the JavaScript
   library:
   ``% ./configure && make``.

5. Install OpenSSL and compile PyOpenSSL
   
   Change to the directory where you installed OpenSSL (for example
   ``c:> cd c:\OpenSSL\``).
   Fix the library names for the mingw compiler:
   ``c:> cd lib\MinGW; move ssleay32.a libssleay32.a; move ssleay32.def
   libssleay32.def``
   Change to the directory where you extracted PyOpenSSL (for
   example ``c:> cd c:\pyOpenSSL-0.5.1``).
   Open a text editor for setup.py and replace 'libeay32' with 'eay32'.
   Then run:
   ``c:> python setup.py build_ext -c mingw32 -I c:\OpenSSL\include
   -L c:\OpenSSL\lib\MinGW build install``

6. Generate the WebCleaner installer
   
   Change to the webcleaner-X.Y directory and run
   ``c:> python setup.py build -c mingw32 bdist_wininst``.

   This generates a binary installer
   ``dist\webcleaner-X.Y.win32-py2.4.exe`` which you just have to
   execute.

   If you installed Psyco please read the `psyco installation docs`_.
   
   .. _psyco installation docs:
      http://psyco.sourceforge.net/psycoguide/node2.html

7. Enjoy
   
   WebCleaner is now downloaded and started as a regular Windows service.
   See the `main page`_ on how to configure the proxy filters.
   
   .. _main page:
      index.html


Troubleshooting
===============

You can search the `webcleaner-users archive`_ if your problem has
already been reported.

.. _webcleaner-users archive:
   http://sourceforge.net/mailarchive/forum.php?forum_id=42921

Troubleshooting for Linux
-------------------------
Errors are logged in the runit log file located at
/var/service/webcleaner/log/main/current

Troubleshooting for Windows
---------------------------
Errors are logged in the system event logger. Execute
Settings -> Control Panel -> Administrative Tools -> Event Viewer
and look at the "Application Log" events.

