Creating a Magic Smoke Server Instance

You need to build and install the system first.

The steps below assume that you are using a Unixoid system. A lot of them will not work on windows, since the makefile for windows does not contain them and the symlinks used inside the server source tree are not present under Windows - you will have to do a lot of manual copying in that case.


You need a (web-)server that has PHP and a database server: Hint: you can check what modules are active in your PHP installation by creating a script file (eg. test.php) that contains only this line: <? phpinfo(); ?> . When you install this file on the web server and then open its URL in a browser it will show you an overview of all PHP functionality. If it returns an empty page, the file was not processed by PHP and you still need to configure the web server.

The database server must be reachable by the web server, but does not need to be on the same machine.

Make sure your web server, and database server work normally.

Database Preparation

Normally you can skip this section for ISP side installations, since your ISP will give you a database and the correct login data for it.

MagicSmoke can work with MySQL or Postgres. Connect to your database server using a client of your choice (I'll assume the command line mysql client below, commands should be similar for other clients).

Create a database user - I'll assume it is called "smoke" and uses "verysecret" as password. Create a database - I'll assume it is called "smoke". Then give the user all rights on this database.

mysql> CREATE USER smoke IDENTIFIED BY PASSWORD 'verysecret';
mysql> CREATE DATABASE smoke;
mysql> GRANT ALL ON smoke.* TO smoke;
MagicSmoke uses a common configurable prefix for its tables ("smoke2_*" per default), so you can use an existing database or even use the same database for multiple installations or different programs (assuming the other programs are as tolerant as MagicSmoke). If you have the possibility it is however recommended to give each MagicSmoke instance its own database, since it is easier to drop and restore entire databases insted of just parts of them.

MagicSmoke2 can be installed in parallel to the old MagicSmoke 1.0 packages, but it cannot access the same tables (upgrade is possible though).

Server Instance Creation

You can skip this part for ISP side installations, instead follow the instructions for Installation on an ISP Account below.

Either install the server package or use the sources in www directly. For each instance you have to chose a target directory in which you want to configure it.

Execute /usr(/local)/share/magicsmoke2-server/install.sh with your target directory as parameter. This will link the current version of MagicSmoke into the target directory, if you have already made a configuration there it will not touch it.

If the target directory is not already inside the DocumentRoot of your server, link the target directory into your web server - either with a symlink or an Alias configuration statement.

Installation on an ISP Account

If you are using an account at an ISP you usually don't get much access to the server. You still have to make sure that you have support for all required components.

You also need to do a local installation first if you want to install to an external ISP account (unless you have full shell and network access there). It is also recommended to try out MagicSmoke on a local box first. If you do not want to install MagicSmoke into a system directory, just change the PREFIX:
make install-server PREFIX=$HOME/magicsmoke

Copy the local server installation directory to you ISP account with whatever copying mechanism your provider has given you (usually FTP or scp). Rename config.php.template to config.php.

Some providers install several versions of PHP in parallel and detect what version you use by the file suffic that you are using. Try the phpinfo() call from above with different file extensions (eg. .php, .php5) to find out what is needed to be interpreted as a PHP 5 (version 5.2 or newer) script. Rename exactly the scripts index.php, admin.php, and machine.php to the correct suffix. Do NOT change any other script names - these are the only ones executed directly and they rely on the other script names still being as delivered.

You will usually get a MySQL database and a matching user name from your provider. You can skip the basic DB creation, configure the parameters you got from the provider and then go on with the configuration as described below.

Configuring MagicSmoke

Now edit the config.php file, it is a simple PHP file. Although theoretically all facilities of PHP are available there, you should stick to the format of the template to avoid unintended side-effects.

The configuration file contains several sections:

Database Options

The database section describes which database is used for storing data and how the database interface behaves.

The $db variable is supposed to point to an object of a class derived from DbEngine. There are currently two of those:

Examples and directions are available in the configuration file template.

The $olddb variable if set can be used to upgrade a MagicSmoke 1.0 database to version 2.0. After upgrade you should comment it out.

There is one option stored in the DB-Engine that is only used for database creation and recovery:

This call sets the web-user and web-passcode for the admin.php script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users. Change the second parameter (password) to something else (preferably something hard to guess), so I won't be able to guess your admin password in case you forget to comment it.

Dedicated Client Configuration

This section configures the behavior of the server towards the dedicated client.

There is only one option: the timeout for client sessions. It is safe to leave it at the default setting - making it short potentially confuses the client into re-establishing the connection immediately, if the clock between server and client are significantly off, making it longer does not have any effect since the client automatically renews the session when it nears its end.

Web Client Configuration

This section configures the behavior of the web interface.

These options configure the timeouts of cookies, what features are available to users and what features of the template engine are available.

Database Initialization

Open a browser and direct it to admin.php in your MagicSmoke installation (usually something like http://localhost/magicsmoke/admin.php). The default user name is "Admin" and the password is "SmokeInMyEye" - or whatever you have configured above.

Click the create database button.

Initial Installation

Create an initial administrator user using the form at the bottom of the page.

Open the client and create a host key for it - upload this host key using the admin form and allow the initial administrator to use any host.


Upgrade from MagicSmoke 1.0

MagicSmoke2 is not able to import old MagicSmoke Backups, you need to import those with an old installation and then convert them as described below.

If you have set up the $olddb variable in your configuration MagicSmoke will offer to migrate data. Do not attempt migration if your new database already has some data stored.

Please make sure that the old and new database do not share tables - at the very least the database name or the table prefix should be different.

The upgrade may take some time - you should make sure that PHP scripts do not abort too soon. On a normal workstation this will take about 2-4 minutes for a database with a few thousand orders. If it fails you should empty/recreate the new database and start over.

Simply enter "upgrade" into the input line and click the button.

Make sure you have an administrator user that can log in. You will have to either export the host key of your old client and import it in the new client or create a new key and import it with the admin form.

The format of customers in the database has changed significantly. The upgrade process tries to guess what part of customer names and customer address belong to which detail. This heuristic may fail in some cases, you should go through your customer list and correct any mistakes afterwards.

When you are done comment out the $olddb configuration to avoid initializing it for every call of a script.

The migration process does not touch the old tables.


Comment out the "setAdminPassCode" line in config.php, so that no one else can abuse this interface.

From now on you can access it with the MagicSmoke client. Your URL for the client ends in machine.php (eg. http://localhost/magicsmoke/machine.php).

Creating Templates

The template/* sub-directories of your target directory contain collections of template files. These are used to generate the user interface that users get to see. Each sub-directory of template is the name of a language in ISO 639 coding - e.g. "en" stands for English, "de" for German, etc. The link "C" (upper-case) points to your fall-back language that is used if the users browser does not support one of the available languages.

Please read the chapter about Template Design and create your own set of templates (or customize an existing one).

If you plan to store your templates in a different directory modify the template line in your config file, eg.: