How to set-up a SiteFusion server

Here we will try to provide you with all information needed to setup a SiteFusion server and connect to it using the SiteFusion client.

Requirements

Make sure these packages are installed: PHP5 (at least 5.2.4, or 5.3), including the CLI (command line interface), MySQL and Apache2 (although other webserver software will probably do just fine). The SiteFusion daemon was written for Linux and Unix(like) POSIX operating systems. Mac OS X has been proven fine as well, but the version of PHP supplied with Mac OS X does not include some of the modules necessary to run SiteFusion. Equally, default linux repository installations often don't include these modules, so you might have to add them separately. On Mac OS X, this is only possible if you replace the default PHP installation with the one on MacPorts. Here's a good tutorial on how to install an apache/php/mysql setup through MacPorts. For more information on installing Apache, MySQL, PHP and PHP modules on your linux setup, please refer to the documentation of your specific distribution or portage software. The necessary PHP modules are:

• json (usually part of the default PHP installation these days)
  
• sockets
• posix
• pcntl
  

You can check which PHP modules are installed by typing in the shell:
To check for the required modules easily, use this line:
It should show all four module names, if anything is missing it's not installed.

Installation

Install SiteFusion by downloading a release package or by using subversion. The latest stable version is 5.2.0. Where you see 5.x.x below, replace for the version of your choice.

Subversion
Stable:

Latest development trunk:

Package
In the case of a package, download it and extract:

In my case, the user is called 'dev' and I extracted the package to /home/dev/sitefusion, although a more suitable location for production environments might be /usr/local/sitefusion or something like that, depending on conventions on your operating system or distribution.

Setup

After extracting we need to edit two configuration files. They can be found in the 'conf' directory, named daemon.conf.example and webfrontend.conf.example. If this is your first installation and you don't have custom config files yet, copy the example files to remove the .example part:
The file daemon.conf holds the configuration for the SiteFusion daemon. Open it in your editor, for example nano. The fields you really have to change are databaseUsername, databasePassword, sitefusionPath, logfile and runtimeDirectory. Probably, timezone should be changed as well.

There are basically two scenarios for running the daemon:

• Start as root: Leave the runtimeDirectory and logfile locations to the default system locations, set changeIdentity to TRUE and fill in a safe user (systemUser) and group (systemGroup) for the daemon to change to (like a separate user owning the sitefusion installation directory, or like the nobody or apache/www-data users who should have at least reading permissions in the sitefusion installation directory). Then start as root. The daemon will then change to the safe user and automatically make sure it can use the log and runtime locations as that user.
  
  
• Start as unpriviledged user: Create new runtime and log directories in the sitefusion installation directory (mkdir run && mkdir log) and change the runtimeDirectory and logfile configuration options to have them point to these locations. Set the changeIdentity option to FALSE. Then start as the unpriviledged user.

Note that in neither scenario the daemon will be running as root. In the first it will only start as root and then change to the safe user as soon as runtime and log locations are setup correctly.

Make sure the logfile and runtimeDirectory configuration settings contain a path to a logfile (doesn't have to exist yet) and a path to a directory respectively.

When you're done editing save and close the file. The second file you have to edit is webfrontend.conf. This one concerns the communication between the webserver and the daemon. The options you most certainly have to edit are sitefusionPath, databaseUsername and databasePassword. Feel free to alter the rest if you need to do so. Again, save and close when you are done.

Next, we have to create the sitefusion database. SiteFusion uses the database to hold its process information and job/service configuration. In order to do this, change to the install/ directory. Run the script with:

Again, you have to provide the ip, username and password for your MySQL server. The script creates the database and tables:


After filling the database, it's time to set up permissions for the sitefusion dir. You should give the www and conf subdirectories global read and execute permissions (chmod 755) so the webserver can run the webfrontend PHP files. Run this command from the sitefusion installation directory:

The rest of the installation directory needs to have the same permissions if you plan to run the daemon as root and have it change to a safe user. At least it needs to be readable by the user running the daemon.

The last thing you have to to is add an alias or vhost to the webserver configuration and point it to the SiteFusion www directory. In the case of apache, either add the following configuration to an existing vhost or create a new one.


Notice that you have to point to the www directory in the location you extracted the SiteFusion files to earlier.

After this, reload or restart the webserver to activate your new alias. You can test if things are working by opening a browser and navigating to http://yourip/sitefusion/login.php. If you don't get a 404 or 403 error, you will be fine. Depending on your browser you should see a piece of JSON text indicating an input error, or a download dialog for login.php resulting in a textfile with the same contents.

Getting started up

Now start the SiteFusion daemon application. When running for the first time add the -f option to the shell command, the daemon will stay in foreground and you will be able to read error messages. Navigate to the sitefusion dir and execute either as root (or through sudo) if changeIdentity is on, or as the safe user:

Possible options are:
-d debug mode (same as setting the debug option in daemon.conf to TRUE)
-f stay in foreground (don't daemonize, same as setting the daemonize option in daemon.conf to FALSE)

It should show this:

If no errors occur, you can shut down the daemon by pressing Ctrl+C and restart without the -d and -f options for production environments. If you are planning to debug instead of running production applications, you can choose to run with the option -d. Debug information is then made available through the log, and the debugger in SiteFusion Admin will be enabled to connect to running processes.

The server setup is now completed.

Troubleshooting

Most error messages will be reasonably clear as to what's causing the problem. If you get errors concerning undefined functions, you're probably missing one of the required PHP modules as listed in the Requirements section above.

If the daemon hangs at 'Opening main server socket...', there are a few possible explainations. Either the port is already in use by another program (the default port is 5173), in which case you should change the designated port number in both configuration files in the conf directory. It's also possible that a sitefusion daemon is still running and should be shut down through SiteFusion Admin. If for some reason it became inaccessible, it can be killed. You can check this by running from shell:

If the error refers to the logfile path or the runtime directory path, make sure that these paths are correct and writable to the user running the daemon.

Setting up the client

Time to set up the client! Start off by downloading the client suitable for your platform.

Windows
Unzip and open sitefusion.exe

Linux
Replace 1.x.x for your version, the latest stable is 1.2.0. Then set executable rights for SiteFusion/SiteFusion Connector:
Then double click it in your file manager or execute from shell with:
MacOS X
Open the DMG image and drag the SiteFusion application to your Applications folder. Then run from there.


The client will prompt you for a number of options. Server URL is the URL of the server we just set up. So http://yourip/sitefusion. The example application is the administration application so in the application field fill in 'sitefusion/admin'. You can leave arguments empty. Finally, the default username is 'admin' and the password is 'secret'. This password can be changed by editing the file sfadminPasswd.php.inc in the app/sitefusion/ directory.



Good luck experimenting with all the possibilities SiteFusion can offer you as a developer.

In the next how-to we will focus on how to create a simple application from scratch, using the SiteFusion API.

Comment on this tutorial

Name:
Email:
	Copy the code: