GNU Sovix Installation Guide
Copyright (c) 2006, 2007, 2008 David Englund.
See the end of the file for copying permissions.


BASIC INSTALLATION

Sovix extensively uses PHP scripts which are intrepreted by PHP.

  1. Make sure your system has at least 2 MB of free disk space.

  2. Software dependencies. Make sure you have those softwares installed:

     1) A web server which supports the PHP extension. We recommend Apache
        HTTP Server 2 (apache2).
        Make sure that the web server can run .php and .inc files used by Sovix.
     2) PHP version 5 (php5), at least version 4.3.0 (php4) or higher
        (required by file_get_contents).
        PHP 4 is however no longer under active development so we recommend PHP 5.
     3) Make sure your system has PostgreSQL 7.4 (postgresql-7.4) or higher
        and/or MySQL database server binaries 4.1 (mysql-server-4.1) or higher
        installed _if_ you want to use Sovix template engine (not required
        for regular tasks) and that PHP can run them.
        We recommend PostgreSQL.
     4) Install Apache 2 ITK MPM (apache2-mpm-itk) if you must to execute PHP
        scripts with the permissions of their owners.

  3. Extract sovix-n.tar.gz and rename the directory sovix-n to sovix.

  4. Move the sovix directory to either:

     DOCUMENT_ROOT

       This is the default configuration for files used by Sovix.
       Please refer $sovix__directory__src=$_SERVER['DOCUMENT_ROOT']."/sovix/src";
       in Sovix.php for example.
       You don't have to modify any file if you choose to use DOCUMENT_ROOT.

     User specified location (recommended)

       If you choose not to use GNU Sovix from DOCUMENT_ROOT as stated above,
       you will need to modify files used by Sovix so as to instruct them
       to use a proper path.

       You can do this by changing document_root="/usr/local/src" to the absolute
       pathname where Sovix is installed, in the following line and execute it.

       document_root="/usr/local/src"; for i in $(find sovix/ -name "*.php" -o -name "*.inc"); do perl -pli -e "s|=\\\$\_SERVER\\['DOCUMENT_ROOT'\\].\"/sovix/src\";|=\"$document_root/sovix/src\";|" $i; done

       Change $sovix__directory__document_root in
       dotsovix/files.inc and Templates/Default/include/dotsovix/files.inc
       to this pathname.

       Modify $sovix__url__include in dotsovix/files.inc and
       Templates/Default/include/dotsovix/files.inc to any location that you
       have copied Special/ to in DOCUMENT_ROOT.

       Finally, modify the URL for
       $sovix__url__websrc in dotsovix/files.inc and
       Templates/Default/include/dotsovix/files.inc.
       sovix/websrc/ contain important files (eg login).

  5. In Unix-like operating systems, set owner and group
     for sovix/ and its files for proper configuration.
     You can use the line below, just modify blank:blank with the correct
     owner:group:

     chown blank:blank -R sovix/


    If you want to update files over a network with Sovix then you need
    to set read and write permission for these files. Its easy to do so
    using a for loop as:

    for i in $(find SOMEPATH/ -type f); do chmod 666 $i; done && for i in $(find SOMEPATH/ -type d); do chmod 755 $i; done


  6. Figure out if your web server accepts links without extension.

     Execute http://localhost/sovix/ (if $sovix__url__sovix is set to default in sovix/Sovix.php),
     this should redirect you to http://localhost/sovix/Sovix.

     Sovix loads files in it's own address bar without any extension to make
     stable URLs that could be used for subsequent runs.

     If you get error message like "The requested URL /sovix/Sovix was not
     found on this server.", please try this in your web browser:

     1) Configure Apache HTTP Server to accept URLs without extensions:

        Make sure Apache is configured with MultiViews for directories that
        use Sovix files.

        This is typcially done in the file httd.conf, 000-default or
        00_default_vhost.conf depending of the version of Apache and the
        build for the specific operating system. It should look something like:

        <Directory /var/www/>
          Options Indexes FollowSymLinks MultiViews

     2) If you cannot make the web server accept URLs without extensions:

        Set sovix__url__include_extension to "n" in dotsovix/public.inc. Save the file
        and reload http://localhost/sovix/. This should redirect to
        http://localhost/sovix/Sovix.php.

  7. Make sure that Apache's DocumentRoot does not end with slash (/) to
     avoid duplicated slashes in Sovix. That might cause conflict(s) in the
     program. This is _sometimes_ a default in the configuration files
     mentioned above (httd.conf, 000-default or 000_default_vhost.conf for
     example) so it is worth checking up!
 
  8. As of PHP 4.3.2, PATH_TRANSLATED is no longer set implicitly
     under the Apache 2 SAPI in contrast to the situation in Apache 1,
     where it's set to the same value as the SCRIPT_FILENAME server variable
     when it's not populated by Apache. This change was made to comply with
     the CGI specification that PATH_TRANSLATED should only exist if PATH_INFO
     is defined.
     Apache 2 users may use AcceptPathInfo = On inside httpd.conf to define
     PATH_INFO. -- http://php.net/manual/en/reserved.variables.server.php

     You can check if SCRIPT_FILENAME is used by your PHP version by go to
     http://localhost/sovix/Special/Variables.php in a web browser.

     Its easy to replace SCRIPT_FILENAME with PATH_TRANSLATED in Unix-like
     operating systems in Bash if you _need_ to do so:

     for i in $(find sovix/ -name "*.php" -o -name "*.inc"); do sed -i "s|SCRIPT_FILENAME|PATH_TRANSLATED|g" $i; done

  9. To be able to login to GNU Sovix site with full administrative rights
     (with the command "login"), please add a password and a username to
     respective variables located in dotsovix/private/auth_sovix.inc.php

     For automatic generation of a random password you can run
     http://localhost/sovix/Special/Passgen.php in any web browser, but
     I suggest to choose your $sovix__password on a timed-based mechanism
     since this will allow you to update the password as often as you
     desire (see auth_sovix.inc.php).

  10. Special modes for PHP

     * Sovix command 'shell' uses PHP's function shell_exec() which cannot
       be used if 'safe_mode = On'.
     * Make sure you set 'file_uploads = On' if you want to allow HTTP
       file uploads from Sovix.
       This is usally the default option.

  11. Allocate errors

     Visit http://localhost/sovix/.
     View page source for that page. If you got "</html>" at the end of
     the page, then everything is set up correctly. If not;

     1) View for errors in the web page produced by PHP or;
     2) Look at the page source and see if PHP describes the error there.

     Do NOT go any further if you stuck here. The whole distribution
     requires that .php and .inc files are syntactically and semantically
     valid.

  12. Sovix should be up by now. Go to http://localhost/sovix/ and
      visit 'Tutorial' in the select menu to learn how to set up a website
      with Sovix.

     Files in the sovix directory (excluding private/ subdirectories) are
     readable over networks from Sovix by default. You can for example read
     Sovix.php by execute 'read-file' in the command line at
     http://localhost/sovix/Sovix.

NOTES

Variables and functions that are used by GNU Sovix begin with sovix__ so as to
keep namespace clean. _GET is used to get variables from the URL to manage
forms and to customize CSS.
(e.g. http://localhost/sovix/Sovix?body-background-color=000000)

PROBLEMS

See the file PROBLEMS in etc/ subdirectory for a list of various
problems encountered occasionally, and what to do about them.


COPYING PERMISSIONS

   Permission is granted to anyone to make or distribute verbatim copies
   of this document as received, in any medium, provided that the
   copyright notice and permission notice are preserved,
   and that the distributor grants the recipient permission
   for further redistribution as permitted by this notice.

   Permission is granted to distribute modified versions
   of this document, or of portions of it,
   under the above conditions, provided also that they
   carry prominent notices stating who last changed them.
