</head>
<body>
<h1>Magic Smoke Web Installation</h1>
+<img src="logo.png" alt="logo" valign="left" align="top"/><br/>
<h2>Prerequisites</h2>
-You need a web-server that has PHP and MySQL installed:
+You need a (web-)server that has PHP and MySQL installed:
<ul>
-<li>PHP version 5.x, with at least the following modules:
+<li>A webserver running PHP version 5.x, with at least the following modules:
<ul>
- <li>PDO (Database abstraction layer), and PDO-MySQL (compatible with the installed MySQL database and client-library)</li>
+ <li>Hash or MHash for authentication (although it is possible to work without them it is not recommended)</li>
+ <li>One of the supported Database drivers: currently only MySQL is supported.</li>
<li>PCRE</li>
- <li>XML: ???</li>
-
+ <li>XML driver: dom</li>
+ </ul></li>
+<li>MySQL 4.x or 5.x -- you need full access to at least one database.</li>
+</ul>
+
+Hint: you can check what modules are active in your PHP installation by creating a script file
+(eg. <tt>test.php</tt>) that contains only this line: <tt><? phpinfo(); ?></tt> .
+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.
<h2>Preparation</h2>
-*create DB
-*create templates
+<ol>
+<li>create a database on MySQL (eg. <tt>create database smokedb</tt>)</li>
+<li>create a database user (eg. <tt>create user smokeuser</tt>)</li>
+<li>give this user full access to this database (eg. <tt>grant all on smokedb.* to smokeuser</tt>)</li>
+<li>create a configuration (see below)</li>
+<li>create templates (see below)</li>
+</ol>
+
+All files needed for Web-Installation are in the www-subdirectory.
+
+<h2>Configuration</h2>
+
+Copy the <tt>config.php.template</tt> file to <tt>config.php</tt>, then modify it to suit your
+needs.
+
+<h3>Database Configuration</h3>
+
+Magic Smoke is designed to work with multiple database engines. However, currently only MySQL is
+supported (this does not support mysqli or pdo_mysql).<p>
+
+The <tt>$db</tt> variable needs to be assigned with the correct engine to open the database. Currently only the MysqlEngine exists. This is an example configuration:
+<pre>
+// create engine: server, user, password
+$db = new MysqlEngine("localhost","smokeuser","");
+// set database name
+$db->setDbName("smokedb");
+// set table-prefix (optional)
+$db->setPrefix("smoke_");
+//set this to one of the supported MySQL storage engines for DB creation
+$db->setStorageEngine("InnoDB");
+</pre>
+
+The three parameters to the MysqlEngine constructor are: first the host the database server runs on. Use "hostname:port" if it runs on a non-standard port or ":/path/to/socket" if you want to use the local socket on a Unix system. The second parameter is the username for the database server and the third one the password (empty if no password is necessary).<p>
+
+The <tt>setDbName</tt> call is used to set the database that is used by Magic Smoke. The <tt>setPrefix</tt> call can optionally be used to set a prefix for all table names -- this way a single database can be used for multiple installations of Magic Smoke or even different applications (if the other applications are guaranteed to not touch Magic Smokes tables).<p>
+
+The <tt>setStorageEngine</tt> call can be used to set the table storage engine used by MySQL. Magic Smoke relies on MySQL using a transactional table type. The default is "InnoDB". It is not recommended that you change the default unless you know exactly what you are doing.
+
+<h3>Admin Configuration</h3>
+
+There is one option stored in the DB-Engine that is only used for database creation and recovery:
+<pre>
+$db->setAdminPassCode("Admin","SmokeInMyEye");
+</pre>
+
+This call sets the web-user and web-passcode for the <tt>admin.php</tt> script. After installing the system this line should be commented to prevent anyone from destroying the database or installing more admin users.
+
+<h3>Client Authentication and Session Configuration</h3>
+
+The remainder of the config file contains settings for the dedicated client:
+<pre>
+//Authentication algorithm
+// possible: md5, sha1, sha256, hmac-md5, hmac-sha1, hmac-sha256
+$ClientAuthAlgo="hmac-sha1";
+//hash algorithm library -- the PHP extension/module used for calculation
+// possible: string (md5, sha1 only), hash, mhash
+$HashLib="hash";
+
+//Initial timeout from start of session request to session authentication
+// usually 300s (5min) is a good value
+$ClientAuthTimeout=300;
+//Authenticated session timeout - how long an authenticated session lasts
+// this should usually be a few hours (3600s per hour)
+$ClientSessionTimeout=2*3600;
+</pre>
+
+<tt>$ClientAuthAlgo</tt> contains the algorithm that is used to authenticate the client. You have to make sure that the algorithm selected is a) available in PHP, b) secure enough for your application, and c) available in all clients that are supposed to connect. The algorithms are:
+<table frame="1" border="1">
+<tr><td>md5</td><td>Uses the MD5 hash algorith described in RFC1321. Please note that this algorithm is regarded as broken and should not be used.</td></tr>
+<tr><td>sha1</td><td>Uses the SHA-1 hash algorithm described eg. in RFC3174. Please note that this algorithm is theoretically broken, although the use of this algorithm in Magic Smoke should still be secure for a few years.</td></tr>
+<tr><td>sha256</td><td>Uses the SHA-256 hash algorithm of the SHA-2 hash family. This algorithm is currently recommended as replacement for SHA-1. However, it is currently not supported by any client.</td></tr>
+<tr><td>hmac-md5, hmac-sha1, hmac-sha256</td><td>Uses the same hash algorithms in HMAC mode (see RFC2104). This use is more secure than the plain use of the algorithms. It is recommended to use HMAC.</td></tr>
+</table><p>
+
+<tt>$HashLib</tt> defines what PHP extension is used for calculation of hash values:
+<table frame="1" border="1">
+<tr><td>string</td><td>Doesn't use any extension and instead uses the string functions md5 and sha1. This mode does not support sha256 or any of the hmac-modes.</td></tr>
+<tr><td>hash</td><td>Uses the "hash" extension. This extension supports all modes listed above.</td></tr>
+<tr><td>mhash</td><td>Uses the "mhash" extension. This extension supports all modes listed above.</td></tr>
+</table><p>
+
+The <tt>$ClientAuthTimeout</tt> and <tt>$ClientSessionTimeout</tt> set the two session timeouts. The first timeout defines how long the authentication handshake of the client may last before the handshake is terminated. The second value defines how long a session may be active before it is automatically closed.<p>
+
+<h2>Creating Templates</h2>
+
+The <tt>www/template/*</tt> directories contain collections of template files. These are used to generate the user interface that users get to see.<p>
+
+Please read the chapter about <a href="template.html">Template Design</a> and create your own set of templates (or customize an existing one).<p>
+
+Then modify the template line in your config file, eg.:
+<pre>
+$template="./template/mytemplate/";
+</pre>
<h2>Installation</h2>
-*copy stuff
-*init DB
-*create initial user
+<ol>
+<li>copy the www directory including your configuration and templates to the web server</li>
+<li>navigate to admin.php in your browser, enter the admin name and passcode you configured</li>
+<li>click to create the database</li>
+<li>create an initial admin user in the database</li>
+<li>close the browser</li>
+<li>link the <tt>index.php</tt> script from your other pages, so that customers can find it</li>
+<li>continue with the client installation</li>
+</ol>
+
+
</body>
</html>
\ No newline at end of file
--- /dev/null
+<html>
+<title>Magic Smoke Template Design</title>
+</head>
+<body>
+<h1>Magic Smoke Template Design</h1>
+<img src="logo.png" alt="logo" valign="left" align="top"/><br/>
+
+The web user interface is constructed with templates with just a few dynamic values filled in. Thos templates are found in the <tt>www/template/*</tt> directories. These templates are normal HTML (actually: you chose the version of HTML that is used) with some special constructs to fill in the blanks.<p>
+
+In order to create your own templates copy one of the template directories and start to modify the files in there. Usually it should be enough to change the <tt>layout.html</tt> template. If you use relative links inside your templates they will be interpreted as relative to the <tt>index.php</tt> script.<p>
+
+<h2>Syntax</h2>
+
+The most important element of templates are variables. Variables can be set by the template itself, or by the script. Wherever the value of a variable needs to be inserted it is simply placed between two "@" characters, eg. "<tt>Variable XYZ contains @XYZ@</tt>". These value replacements can occur anywhere in the text, whereas all other syntactical elements must appear on a line of their own.<p>
+
+Variables can be set and unset using the special <tt>#set</tt> and <tt>#unset</tt> commands:
+<pre>
+#set:VARIABLE=value
+#set:LONGVARIABLE:
+some values containing anything
+#endset
+</pre>
+
+The first version of the set-syntax just assigns everything behind the "=" to the variable named before it. The second version of the set-syntax assigns everything between the <tt>#set</tt> and <tt>#unset</tt> lines without replacing any values or interpreting any syntax.<p>
+
+Conditional parts of the template text can be put between <tt>#if</tt> and <tt>#endif</tt>:
+<pre>
+#if:VARIABLE==value
+text that only appears if VARIABLE contains value
+#endif
+</pre>
+All comparisons are made as string comparisons (this eg. means "2" is greater than "100") with both the variable and the comparison value trimmed. Possible operators are:
+<table frame="1" border="1">
+<tr><td>==</td><td>matches if the variable contains exactly this value</td></tr>
+<tr><td><</td><td>matches if the variable is smaller than this value</td></tr>
+<tr><td>></td><td>matches if the variable is greater than this value</td></tr>
+<tr><td><=</td><td>matches if the variable is smaller or equal to this value</td></tr>
+<tr><td>>=</td><td>matches if the variable is greater or equal to this value</td></tr>
+<tr><td>!= or <></td><td>matches if the variable does not contain this value</td></tr>
+</table>
+
+<h2>Template Files</h2>
+
+<h3>layout.html</h3>
+
+This is the main template that contains the static parts of all pages displayed by Magic Smoke.<p>
+
+The only variable inside it is <tt>@PAGE@</tt> which is replaced by the context created using one of the other templates.
+
+
+</html>
\ No newline at end of file
projects / web/konrad/smoke.git / commitdiff