Spark/Plug Installation Instructions ==================================== Spark/Plug is designed to be very flexible and simple to install. Simple Installation Method ========================== The simplest installation method is to simply unpack the Spark/Plug package into a directory inside your web server's document root. For example: $ cd /var/www/htdocs $ gunzip sparkplug.hz This will give you a layout like this: /var/www/htdocs/ sites/ blog/ welcome/ sparkplug/ apps/ blog/ welcome/ languages/ plugs/ sparkplug.php views/ You should now be able to visit the sample apps in your web browser by navigating to http://mydomain.com/sites/welcome and http://mydomain.com/sites/blog Advanced Installation Method ============================ There are drawbacks to the Simple Installation Method. For one thing, it complicates sharing a single installation of the Spark/Plug files across apps served in different domains. It also forces the "sites" directory to appear in your URLs (although there are ways to work around this). And it is generally more secure to keep your application code (.php files) outside of your web server's document root, as this prevents the inadvertant leakage of sensitive files such as configuration files containing user names and passwords. For these reasons, the recommended approach is to install the main Spark/Plug directory (the one that contains the sparkplug.php file) inside a shared directory outside of your web server's document root. For example, on Unix-like systems, a fine choice would be /usr/share/local/sparkplug. In this case, your core Spark/Plug install would look like this: /usr/share/local/ sparkplug/ apps/ blog/ welcome/ languages/ plugs/ sparkplug.php views/ Individual Spark/Plug apps should be split into two parts: application code (i.e. .php files), and public downloadable assests (eg. css, images & scripts). The application code should be installed outside of the web root. The sparkplug/apps/ directory may be used for this purpose, although the recommended approach is to create your own /apps directory (eg. /usr/share/local/sparkplug-apps). Creating your own /apps directory simplifies the process of upgrading Spark/Plug, since you can simply copy over the entire Spark/Plug directory without worrying about accidentally deleting your apps. Your app's public assets must be loacated inside your web server's document root so that the web server is able to serve them directly to your app's users. In order to bootstrap your Spark/Plug application, you will need to place one .php file into the app's site directory (under the document root). This file (index.php) simply includes your app's main .php file from your sparkplug-apps/ directory like so: include('/usr/share/local/sparkplug-apps/blog/app.php'); After following the above approach, your Spark/Plug layout would look something like this: /usr/share/local/ sparkplug/ languages/ plugs/ sparkplug.php views/ sparkplug-apps/ my-blog-app/ app.php my-forum-app/ app.php my-cms-app/ app.php /var/www/htdocs/ my-blog-site/ index.php css/ img/ js/ my-forum-site/ index.php css/ img/ js/ my-cms-site/ index.php css/ img/ js/ Which Installation Method to Choose =================================== So, given the above, which installation method should you choose? If your web host does not give you access to upload files outside of the web server's document root, then you have no choice but to use the Simple Installation Method. You should still be fairly secure, as Spark/Plug does take precautions to prevent direct access to its source files. If you do have permissions that allow you to upload files outside of your web server's document root (eg. to /use/share/local/), then we encourage you to use the Advanced Installation Method. It is more flexible, more secure, and easier to upgrade.