sf-active v0.98 setup process

This describes the procedure of setting up sf-active 0.98 (at the moment the CVS version) manually, most of it will be done by an installer script later. The idea is to simplify this procedure and hand over more and more parts to an install script.

FIXME: there should be an introduction of what sf-active is and how it basically works (especially the seperation of static and publish), so even non-tech people get a basic idea of how all the stuff works. there might be also the need to explain some basic terms like "cache" etc because non-tech people will have no idea of what this is about (in the admin area e.g.)

Manual Installation

1. Requirements

Check if all requirements are met. Make sure you have the following installed/available.

• apache
• mysql-server 4.1
• php4 (minimum 4.3)
  • the webmodule for apache
  • the command line interface.
• php4-mysql
• smarty

FIXME: i listed the debian packages here, i have no idea how this works on e.g. freebsd. did anybody ever tried if the whole stuff works with php5 ??

sf-active does not currently work with php5 -- MattToups - 01 Jan 2006

Set up a user dedicated to sf-active. In this example it is called sfa, and the home directory of that user is /home/sfa.

# useradd sfa

or

# adduser sfa

on other systems.

2. Getting the code

You have two options:

• Download the tar.gz file to the home directory of your user, i.e. to /home/sfa/scfactive-version.tar.gz, and unpack it:
  $ tar xzzvf scfactive-version.tar.gz
• Check out the latest release from CVS. Instructions on how to do this are available on the sf-active download page. Remove any unneccessary files and directories such as of the CVS directories, and make sure your directory structure meets the one of the release package (see below).

Now you should have a directory structure similar to this:

/home/sfa/
         doc/
         debian/ 
         sf-active/
                  install/
                  shared/ 
                  sitename/
etc ...

3. Setting permissions

Now you have to change the file permissions.

• You can use the script included in the distribution, that's /home/sfa/sf-active/install/sfa-perm.sh. Read on below for more info.

You have to run the script as root.

It takes three arguments:

• the sf-active user (sfa in this example)
• the web server user, that's commonly one of www, www-data, apache. Check /etc/passwd to find out.
• the path to the 'sitename' directory (/home/sfa/sf-active/sf-active/sitename/ in this example).

Example call:

$ sudo ./sfa-perm.sh sfa www-data /home/sfa/sf-active/sf-active/sitename/

This sets the permissions in your sitename/ directory. For your site to work correctly, you'll have to chown the sessions paths to the webserver user:

 $ sudo chown www-data /home/sfa/sf-active/sf-active/shared/session

4. Preparing the database

if you have a databse setup allready, you now need:

• host
• database_name
• user_name
• password

go to the install directory

$ cd /home/sfa/sf-active/install

and use the db_patch.php script:

php db_patch.php /home/sfa/sf-active/install/current localhost db-user dbname db-password

and hit yes when prompted

5. Setting up the virtual hosts

Now it's about time to create the virtual host entries for the sfactive sites. To have everything in the same place, you can create this is as an include file to the general web server configuration and store the part that relates to sf-active in /home/sfa/.

To do so, create /home/sfa/sfa_vhost (or wherever you want to place it) and add the following to it:

<VirtualHost xx.xx.xx.xx>
ServerName public.yourdomain.org
DocumentRoot /home/sfa/sf-active/sitename/website
setenv SITE_NAME sitename
php_value include_path .:/usr/share/php/smarty/libs:/home/sfa/sf-active/sitename:/home/sfa/sf-active
# errors are on for debugging only
php_flag display_errors On
php_flag magic_quotes_gpc Off


   <Directory "/home/sfa/sf-active/sitename">
     Options +Indexes  
   </Directory> 
</VirtualHost>

Make sure the paths given in it match your current setup. You also need to replace the "xx.xx.xx.xx" by the IP address of your server or by an asterisk (*). This depends on what your NameVirtualHost directive is set to.

FIXME: there should be also a scenery if people like to setup the publish part on ssl, apart from i have no idea if all the links still work than, was this ever discussed somewhere ?

Now you have to edit the main configuration file of Apache, httpd.conf (or apache.conf if the other doesn't exist). You will liekely need to do that as root.

# cd /etc/apache/

and add the following line to your httpd.conf.

Include /home/sfa/sfa_vhosts

This line goes very much to the bottom of this file, look for other lines starting with 'Include' and place it after them.

Now you have to restart the webserver, but before that check whether the Apache configuration file syntax is allright:

# apachectl configtest

If you get an "OK" then run

# apachectl restart

or, on Debian,

# /etc/init.d/apache restart

6. Editing the config files

edit /home/sfa/sf-active/shared/global.cfg

set the root directory of your installation

$server_root = "/home/sfa/sf-active/";

edit the following part according to your needs:

if ($site_name) 
{
    switch ($site_name)
    {
        case "sitename":
            $config_dir = $server_root . "/sitename/local/config";
            $time_diff = 0;
            break;
   default:
      $config_dir = $server_root . "/sitename/local/config";
      $time_diff = 0;
    }
} else
{
    $config_dir = $server_root . "/sitename/local/config";
    $time_diff = 0;
}

the idea of running serveral websites by setting up more than one "sitename" directory should be explained in easy words. however, the question if a multi-site setup should be done manually anyway, because writing an installer for that could be hell

edit /home/sfa/sf-active/sitename/local/config/sfactive.cfg

normally you only want to change setting in this part of the file

/* *** Database *** fill in the correct values for your database */
define('DB_HOSTNAME',   DB_SHARED_HOST);
define('DB_USERNAME',   'database username');
define('DB_PASSWORD',   'databasepassword');
define('DB_DATABASE',   'databasename');
define('DB_VENDOR',     'mysql');

/* *** Main Paths *** if you didn't do anything funky, you should
    only change SF_BASE_PATH */
define('SF_BASE_PATH',     '/path/to/sf-active');
define('SF_INSTALL_PATH',  SF_BASE_PATH . '/sitename');
define('SF_SHARED_PATH',   SF_BASE_PATH.'/shared');
define('SF_LOCAL_PATH',    SF_INSTALL_PATH.'/local');
define('SF_STATIC_PATH',    SF_INSTALL_PATH.'/static');


/* *** URLs ***
    * SF_ROOT_URL: your main site url. like sfa.indymedia.org
    * SF_PUBLISH_URL: change this when you run your admin/publishing from a different
        domain.
    * SF_SEARCH_URL: change this value if you use different servers to read from your database
    * SF_SEARCH_URL: change this if you use a dedicated server(s) to serve multimedia files
*/
define('SF_ROOT_URL',       'http://sfa.indymedia.org');
define('SF_PUBLISH_URL',    'http://sfa.indymedia.org');
define('SF_SEARCH_URL',     'http://sfa.indymedia.org');
define('SF_UPLOAD_URL',     'http://sfa.indymedia.org');

Hint: The search and upload URLs are only used if you want searches to run on a different machine. FIXME: more documentation is needed here, esp. for the URLs

edit /home/sfa/sf-active/sitename/scripts/cli.cfg

set the include_path and the sitename to the same values you've used in your virtual host configuration

7. Setting up the website

Now you basic site is set up. you should be able to go to your site. You get a default screen welcoming you. This is far from the basic site you want. Follow the instructions here to cache a basic site.

Setting up the language environment

There should be a default language english. If you wish another language, edit that language. You can add languages too off course. Make sure at least one language has the option to build a site for it checked.

Cache your basic site.

Go again to the scripts directory: /home/sfa/sf-active/sitename/scripts and execute the following script:

$ php ./cli_initialise.php

after that, set up your permissions to something sane again (run this as root):

$ ./site_perm.sh sfa www-data /home/sfa/sf-active/sf-active/sitename/

Set up the cron system

• Edit /www/sf-active/shared/sfcrons.php: change the CLI path, and the path to the shared config file.
• edit /www/sf-active/shared/sfcrons.cfg: change the sitedir path
• add an hourly, daily, weekly, and monthly entry in your crontab. each entry should look like this: /usr/bin/php4 /www/sf-active/shared/sfcrons.php [hourly|daily|weekly|monthly].

note that you should specify the time in crontab so that it runs at the appropriate time -- the cron system will just run the scripts in the appropriate subdirectory. This only needs to be done once globally, and not repeated for each site; it will be able to determine automatically where to find the site directories.

Automatic installation

Sorry. Currently there is no automatic installation script. Please use the manual one for now.

This section gathers information which will be used to provide an automatic installation script in the future.

Installer Script

imho i think that almost everything can be created by a installation process as a shellscript. (rather then a php script because for that the vhosts must exist first) let's call it "install-sfa.sh" for now

the script should ...

1) ask for all neccessary information

• database_host
• database_name
• user_name
• database_password

name of the user (getting the home directory path) maybe change of "sitename"

Next steps (without any action from the user)

2) creating db, db user and putting data into database

This must be done as the mysql root user (or another user having equal permissions), other than that it will not work.

CREATE DATABASE `sfa` DEFAULT CHARACTER SET latin1 COLLATE latin1_general_ci;
GRANT USAGE ON * . * TO 'sfa'@'%' IDENTIFIED BY '****' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 ;
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, CREATE TEMPORARY TABLES ON `sfa` . * TO 'sfa'@ '%';

3) creating the vhost file

4) generating the config files

5) running the perm-script

6) making the symlinks

7) first generation of static_pages and includes should be done automatically

up and running

-- PseudoPunk - 27 Dec 2005 (Fixed bugs in code and adapted text to it)

-- StartX - 10 Sep 2005

-- AlsteR - 22 Oct 2005