<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>b2evolution Automated Install</title>
</head>
<body>
<h1>b2evolution Automated Install/Upgrade</h1>
<p>Updated for version 6.6+</p>
<p>See <a href="http://b2evolution.net/man/automated-install">the online manual</a> for additional information.</p>
<h2>Purpose</h2>
<p>This document describes how you can most easily automate the installation of <a href="http://b2evolution.net/">b2evolution</a> on a hosting account.</p>
<p>This document also addresses automated upgrade of b2evolution.</p>
<h2>Intended audience</h2>
<ul>
<li>Web hosting providers</li>
<li>Web hosting tool providers</li>
</ul>
<h2>Operating environment</h2>
<p>b2evolution is a PHP + MySQL web application. Please see our <a href="http://b2evolution.net/man/system-requirements">System Requirements page</a> for details.</p>
<h2>Basics</h2>
<p>Automated installation of web applications such as b2evolution typically involves these steps:</p>
<ol>
<li>Place the application files in the destination directory.</li>
<li>Create a MySQL User, Database and privileges of the user on the database.</li>
<li>Run the install/setup script of the application.</li>
<li>Delete the installer.</li>
</ol>
<h1>Recommended Auto Install procedure</h1>
<h2>1. Place the application files in the destination directory</h2>
<p>We recommend you prompt the user for a directory to install b2evolution into. If he provides an empty directory, b2evolution would be installed in his web root. This is the recommended default as b2evolution is a complete engine allowing to run a complete website (or even more if there are domain aliases pointing to the same folder.)</p>
<p>Let's assume the user chose to install into the root folder (www/).</p>
<p>Once the destination directory selected/created, you need to copy all the contents of the b2evolution package into the destination directory www/.</p>
<h3>File permissions</h3>
<p>You should make sure that the contents of the www/media/ directory are writable by PHP. This is the place where the user can upload pictures to insert in his blog posts, etc.</p>
<h2>2. Create a MySQL database</h2>
<p>You will need to provide b2evolution with a database where it will create its own tables.</p>
<h2>3. Run the install script</h2>
<p>At this point you can call b2evolution's install script through an HTTP GET request (wget, cURL, etc..) of this form:</p>
<pre>http://example.com/install/index.php?locale=en-US&action=newdb&create_sample_contents=full</pre>
<h3>Use this form to generate an automated install test URL:</h3>
<form action="index.php" method="get" style="background-color:#ddd">
<input type="hidden" name="action" value="newdb" />
<input type="hidden" name="create_sample_contents" value="all" />
<input type="hidden" name="locale" value="en-US" />
<fieldset>
<legend>General</legend>
<p>
<label>Base URL:</label>
<input type="text" name="baseurl" /> <small>leave blank for auto detection</small>
</p>
<p>
<label>Display:</label>
<label><input type="radio" name="display" value="normal" /> Normal</label>
<label><input type="radio" name="display" value="compact" checked="checked" /> Compact</label>
</p>
</fieldset>
<fieldset>
<legend>DB Access</legend>
<p>
<label>MySQL Username:</label>
<input type="text" name="db_user" value="demouser" />
</p>
<p>
<label>MySQL Password:</label>
<input type="text" name="db_password" value="demopass" />
</p>
<p>
<label>MySQL Database:</label>
<input type="text" name="db_name" value="b2evolution" />
</p>
<p>
<label>MySQL Host/Server:</label>
<input type="text" name="db_host" value="localhost" />
</p>
<p>
<label>MySQL Table prefix:</label>
<input type="text" name="db_tableprefix" value="evo_" />
</p>
</fieldset>
<fieldset>
<legend>Admin Account</legend>
<p>
<label>Login:</label>
<input type="text" name="admin_login" value="admin" /> <small>b2evolution may decide to use "admin" if you provide an invalid login. The installer will tell you the final login used. (see "Detect success" below).</small>
</p>
<p>
<label>Password:</label>
<input type="text" name="admin_password" value="demopass" /> <small>Leave blank to get a random pwd. b2evolution may decide to use a random password if you provide an invalid password. The installer will tell you the final password used. (see "Detect success" below).</small>
</p>
<p>
<label>E-mail:</label>
<input type="text" name="admin_email" value="postmaster@localhost" />
</p>
</fieldset>
<fieldset>
<legend>Technical options</legend>
<p>
<label>.htaccess handling:</label>
<select name="htaccess">
<option value="test">Test if supported & install if no .htaccess found</option>
<option value="force">Force writing/updating .htaccess to latest version</option>
<option value="skip">Don't try to install .htaccess</option>
</select>
</p>
</fieldset>
<p>
<input type="submit" value="Test Automated Install" />
</p>
</form>
<h3>.htaccess</h3>
b2evolution comes with a sample.htaccess file that it will try to copy to .htaccess. This will fail if there is already a .htaccess file present. Please make sure b2evolution can install its own .htaccess file or many features related to parsing extended URLs will fail.
<h3>Detect errors:</h3>
<p>If you parse the output of the installer, you will find that potential errors will be marked in <evo:error>...</evo:error> and warnigns with <evo:warning>...</evo:warning>.
<p>Here is a list of all possible errors & warnings:</p>
<ul>
<li><evo:error>ERROR: Impossible to rename <code>/media/users/admin/</code> to <code>/media/users/xyz/</code>.</evo:error></li>
<li><evo:error>ERROR: Impossible to use "xyz" for the admin account. Using "admin" instead.</evo:error></li>
<li><evo:error>Logins can only contain letters, digits and the following characters: _ . -</evo:error></li>
<li><evo:error>Logins cannot start with "usr_", this prefix is reserved for system use.</evo:error></li>
<li><evo:error>The minimum password length is 5 characters.</evo:error></li>
<li><evo:error>Passwords cannot contain the characters <, > and &.</evo:error></li>
<li><evo:error>The email address is invalid.</evo:error></li>
<li><evo:error>There is already a file called .htaccess at the blog root. If you don't specifically need this file, it is recommended that you delete it or rename it to old.htaccess before you continue. This will allow b2evolution to create a new .htaccess file that is optimized for best results.</evo:error></li>
<li><evo:error>ERROR!<br><b>Again, we recommend you remove this file before continuing. If you chose to keep it, b2evolution will probably still work, but for optimization you should follow <a href="http://b2evolution.net/man/htaccess-file" target="_blank">these instructions</a>.</b></evo:error></li>
<li><evo:error>ERROR!<br><b>Cannot find file [ sample.htaccess ] in your base url folder.</b></evo:error></li>
<li><evo:error>ERROR!<br><b>Failed to copy files!</b></evo:error></li>
<li><evo:error>ERROR!<br><b>http://example.com/install/test/index.html was not found as expected.</b></evo:error></li>
<li><evo:error>ERROR!<br><b>Test was successful, but failed to copy .htaccess into baseurl directory!</b></evo:error></li>
<li><evo:error>The DB schema has been changed since confirmation.</evo:error></li>
<li><evo:error>b2evolution cannot be installed, because of the following errors:</evo:error></li>
<li><evo:error>It seems that the database config settings you entered don't work. Please check them carefully and try again...</evo:error></li>
<li><evo:error>You must pass db_config params or create a <code>/conf/_basic_config.php</code> file before calling the installer.</evo:error></li>
<li><evo:error>Could not load original conf file [/conf/_basic_config.php]. Is it missing?</evo:error></li>
<li><evo:error>No default time zone is set. Please open PHP.ini and set the value of 'date.timezone' (Example: date.timezone = Europe/Paris) or open /conf/_advanced.php and set the value of $date_default_timezone (Example: $date_default_timezone = 'Europe/Paris';)</evo:error></li>
<li><evo:error>ERROR: Impossible to connect to Database.</evo:error></li>
<li><evo:error>Check your database config settings below and update them if necessary...</evo:error></li>
<li><evo:error>In order to install b2evolution with the en-US locale, your MySQL needs to support the utf-8 connection charset. (mysqli::set_charset(utf8))</evo:error></li>
<li><evo:error>Upgrade failed!</evo:error></li>
<li><evo:warning>OOPS! It seems b2evolution is already installed!</evo:warning></li>
<li><evo:warning>Already installed.</evo:warning></li>
<li><evo:warning>Not Enabled: You should create at least one question!</evo:warning></li>
<li><evo:warning>WARNING: this plugin can only work once you download the GeoLite Country DB database. Go to the plugin settings to download it.</evo:warning></li>
<li><evo:warning>You must configure a ping service URL before the plugin can be enabled.</evo:warning></li>
</ul>
<h3>Detect success:</h3>
<p>You can detect that installation has been successful by parsing the output and locating the string <evo:password> .</p>
<p>Furthermore, you can parse out the password that has been created for the user by parsing it out between <evo:password> and </evo:password>. Example:</p>
<pre><evo:login>admin</evo:login></pre>
<pre><evo:password>Htf8s*d/Kp$q6</evo:password></pre>
<h2>4. Delete the install folder</h2>
<p>At this point, the www/install/ folder is no longer needed. We recommend you delete it, both to save space and improve security.</p>
<p>Note: when upgrading, you will need a <strong>new</strong> version of the install folder. So there is really no point in keeping the old one.</p>
<h1>Recommended Auto Upgrade procedure</h1>
<p>Any newer version of b2evolution can upgrade its database from any older version. It will also refuse to update if for some reason you try to "downgrade" it.</p>
<h2>0. Detecting which version of b2evolution is installed</h2>
<p>Open the file www/conf/_application.php and parse out the line that says:</p>
<pre>$app_version = '6.1.0-alpha';</pre>
<p>You can safely ignore the part after the hyphen (-). The version <strong>number</strong> will always change when a new version is released.</p>
<p>You can compare this version number with the new one you have available.</p>
<p>Note: if using PHP, you can use version_compare() which does all the work for you.</p>
<h2>1. Getting confirmation that the user wants to upgrade</h2>
<p>You should warn the user that any customizations he may have added to his existing b2evolution may not work properly with the new version. This especially applies to custom skins, custom plugins and custom locales (translations).</p>
<p>Optionally, you may want to provide checkboxes for the following:</p>
<ul>
<li>Reset skins</li>
<li>Reset plugins</li>
<li>Reset locales (translations)</li>
</ul>
<h2>2. Replacing the files</h2>
<p>Delete all files & folders from the b2evolution root folder except:</p>
<ul>
<li> <strong>www/media/</strong> (where the user has uploaded his content files).</li>
<li>If the user hasn't explicitely requested a reset of these, also keep:
<ul>
<li><strong>www/skins</strong>/</li>
<li><strong>www/plugins/</strong></li>
<li><strong>www/locales/</strong></li>
</ul>
</li>
<li><strong>www/conf/_basic_config.php</strong> (You need to keep the basic config, otherwise b2evolution cannot upgrade)</li>
</ul>
<p>After that, copy all files from the new b2evolution's distribution package.</p>
<h2>3. Upgrading the database</h2>
<p>At this point you can call b2evolution's install script through an HTTP GET request (wget, cURL, etc..) of this form:</p>
<pre>http://example.com/install/index.php?locale=en-US&action=evoupgrade</pre>
<p>Use this form to generate an automated upgrade test URL:</p>
<form action="index.php" method="get" style="background-color:#ddd">
<input type="hidden" name="action" value="evoupgrade" />
<input type="hidden" name="locale" value="en-US" />
<fieldset>
<legend>General</legend>
<p>
<label>Display:</label>
<label><input type="radio" name="display" value="normal" /> Normal</label>
<label><input type="radio" name="display" value="compact" checked="checked" /> Compact</label>
</p>
</fieldset>
<fieldset>
<legend>Technical options</legend>
<p>
<label>.htaccess handling:</label>
<select name="htaccess">
<option value="test">Test if supported & install if no .htaccess found</option>
<option value="force">Force writing/updating .htaccess to latest version</option>
<option value="skip">Don't try to install .htaccess</option>
</select>
</p>
</fieldset>
<p>
<input type="submit" value="Test Automated Upgrade" />
</p>
</form>
<h2>4. Delete the install folder</h2>
<p>At this point, the www/install/ folder is no longer needed. We recommend you delete it, both to save space and improve security.</p>
<p>Note: when upgrading again, you will need a <strong>new</strong> install folder. So there is really no point in keeping the old one.</p>
<h1></h1>
</body>
</html>