![[Note]](/images/stories/docimport58/note.png) | Note |
|---|---|
If you are using Kickstart as part of the JoomlaPack component's integrated restoration feature, you can safely skip this section. All of this is taken care for you already. |
Kickstart is part of the release system and is distributed under the package name kickstart_VERSION.zip, where VERSION is the release version of Kickstart (usually the same as the release version of the JoomlaPack component itself). You can get it the same way you can get the JoomlaPack component.
![[Tip]](/images/stories/docimport58/tip.png) | Tip |
|---|---|
From time to time we may release Kickstart updates inbetween official releases of the JoomlaPack component. In such a case we will post a release announcement on our website. Release announcements can be read right from the JoomlaPack component. Just look for the "JoomlaPack news" pane in the Control Panel! |
JoomlaPack's Kickstart requirements generally match those of Joomla! 1.5.x :
PHP 4.3.10 or greater
Apache 1.3 or above (should now work with IIS, but it hasn't been tested)
PHP mod_zlib available
PHP Safe Mode disabled, or correct directory ownerships, or FTP connection parameters must be entered
The last requirement must be further explained. PHP with Safe Mode enabled will refuse to create folders inside another folder which is not owned by the same user as the one the web server (Apache) runs under, even if the folder is otherwise writable. Kickstart will fail in this case. Alternatively, if you supply the FTP connection information, Kickstart will try to use FTP to connect to your site and write the extracted files.
![[Important]](/images/stories/docimport58/important.png) | Important |
|---|---|
Even with the FTP mode, Kickstart still requires your site's root to be writable. Kickstart extracts each file from the archive as a temporary file in your site's root first, then stores it by means of FTP to its final location and finally removes the temporary file. If the temporary file can't be written to, Kickstart will fail. |
Moreover, if you already have a site installed on the target server you have to ensure that all folders and files are writable. If not, Kickstart will fail and leave your site in a possibly broken state.
If you intend to use Kickstart on a live site, we recommend using the password protection feature. This will keep unpleasant surprises to a minimum while you restore or update your site.
In order to enable the password protection feature, you will have
to edit the kickstart.php file. Find the line
reading:
//define('PASSWORD', '1234'); // Password to access the main pageand replace it with:
define('PASSWORD', 'yourpassword');Of course, you have to replace
yourpassword with a password of your own.
Kickstart will detect this upon launching and prompt you for this
password before proceeding.
![[Warning]](/images/stories/docimport58/warning.png) | Warning |
|---|---|
The password protection only prevents unauthorised access to Kickstart's first page (the settings page). If an attacker knows the name of a valid archive file in your site he will be able to bypass this protection by supplying data directly to Kickstart. In other words, the password feature offers a minimal degree of protection . |
| Note |
|---|---|
The "Automatic Mode" is only usable with backup archives which include the JPI3 embedded installer. If you have the newer, JPI4 embedded installer, please see the next section. |
Since JoomlaPack 2.0.b1, Kickstart is equipped with the optional "Automatic mode" which allows for single-click site restoration or migration. The concept is simple: after you click the button the backup archive is extracted, JPI3 is fired up, it automatically goes through the restoration pages and - finally - control is returned to Kickstart which cleans up. In other words, you click the button and everything takes care of itself! This feature can be used for automated restoration on the same host (backup restoration) or on a different host (site migration).
| Tip |
|---|---|
The "Automatic mode" is very handy for web developers who want to regularly test their in-progress sites on a live host. As a matter of fact, it has been developed with close cooperation with a professional web developer to ensure it would live up to your expectations. |
| Note |
|---|---|
The "Automatic mode" can optionally be used together with the password protection feature for an increased level of security, |
In order for JPI3 to know what are the valid database connection
details for the target host, Kickstart has to provide them. For this to
happen, you'll have to edit kickstart.php to suit
your needs.
To enable the "Automatic mode", edit
kickstart.php and locate this block of
lines:
define('AUTOMODE', 0);
define('DBhostname', '');
define('DBname', '');
define('DBPrefix', '');
define('DBuserName', '');
define('DBpassword', ''); | Important |
|---|---|
Make sure your backup archive was created with JoomlaPack 2.0.b1 or later and that the JoomlaPack Installer 3 was the selected installer to be embedded. In any other case you'll get an error message as soon as JPI is launched and you'll have to manually enter the installation directory's URL in your browser's address bar to effectively perform a manual (normal) site restoration. |
These settings should be changed accordingly. Each one has a specific meaning:
AUTOMODE must be set to 1 for the "Automatic mode" to be effective
DBhostname is your database server's host name (usually it's localhost)
DBname is the name of your database
DBPrefix is the prefix you'd like to use for your site. Most Joomla! sites would opt for the default value of jos_ .
DBuserName is the database user's name
DBpassword is the database user's password
Since Kickstart 2.4, there is the possibility of zero-click site restoration. The only pre-requisite is that your backup archive must be created using the "JoomlaPack Installer 4" (a.k.a. JPI4) embedded installer.
The automation procedure covers the entirety of the
extraction/restoration process. Once you start Kickstart, it will
extract the archive, call the JPI4 installer, it will automatically
proceed through all of its pages and then call the final Kickstart step
which removes kickstart.php, the archive file and
the installation directory.
Everything is controlled by the contents of a single file which
must be named jpi4automation.ini and located in the
same directory as kickstart.php. So, you only need
to upload three files: kickstart.php, the archive and
jpi4automation.ini. If you do that, accessing kickstart.php from your
browser will result in a fully restored site, without any user
intervention (unless an error happens; in this case the process will
halt for you to review and correct the error).
The INI file is comprised of different sections, described below.
The first section controls Kickstart and looks like this:
[kickstart] zipselect=backupfile.jpamethod=ajaxextract=ftpftphost=ftp.example.comftpport=21ftpuser=myuserftppass=mypassftpdir=/public_htmlrestoreperms=onstealth=onstealthurl=http://www.example.com/stealth.html
All those variables correspond to the options you are presented with when running Kickstart. All must be present in the INI file, even if to be left blank.
zipselect. The name of the backup archive (ZIP or JPA) to extract.
method. It can be
ajaxfor Ajax mode orjsfor Javascript Redirects mode.extract.It can be
directfor direct file writes orftpfor the FTP extraction mode.Tip You may want to edit kickstart.php and set a different
TEMPDIR. By default, Kickstart tries to use the directory it is located for extracting files before uploading them through FTP to their final destination. Modifying TEMPDIR to point to a subdirectory with 0777 permissions can help you get around some server setups where the site's root is not writable.ftphost. The hostname of the FTP server, without the ftp:// protocol prefix, e.g. ftp.example.com. Like all other options starting with "ftp" they are only relevant if
extractis set toftp. Otherwise, you can leave it blank.ftpport. The FTP port to use. Normally, it is port 21.
Important Kickstart doesn't support FTPS, SFTP or any other FTP variant. It only supports the "plain" FTP protocol. Do not seek assistance if you have such an FTP host.
ftpuser. The username to connect to your FTP server.
ftppass. The password to connect to your FTP server
ftpdir. The FTP directory where your site is to be restored. You can find this out by launching a graphical FTP client, for example FileZilla, finding where kickstart.php is stored and noting down the FTP path shown. This is the path you have to use in this variable.
restoreperms. Should Kickstart attempt to restore permissions? It can be
onoroff. This is only available with JPA archives.Important This may not work as expected! Kickstart is only able to restore permissions, not ownership. This can lead to an unusable site. If unsure, set to off.
stealth. Should Kickstart redirect visitors to another page while the restoration is in progress? It can be
onoroff.stealthurl. The URL to redirect visitors if
stealthison.
The next section, titled jpi4, contains the basic site setup information to be passed to the JPI4 restoration script. It looks like this:
[jpi4] ftp_enable=off ftp_host=ftp.example.com ftp_port=21 ftp_user=myuser ftp_pass=mypass ftp_root=/public_html sitename=The Site Name mailfrom= This e-mail address is being protected from spambots. You need JavaScript enabled to view it fromname=Site Name Email Notification System sauser=62 sapass1=secret_password saemail= This e-mail address is being protected from spambots. You need JavaScript enabled to view it tmp_path="$SITEROOT/tmp" log_path="$SITEROOT/log"
All parameters are saved on the
configuration.php file of the restored site, or
directly stored in the database.
| Tip |
|---|---|
If PHP throws a warning about parsing jpi4automation.ini and the JPI4 restoration process doesn't proceed automatically, you will have to include all parameters' values in double quotes, like this: myparameter="my_value" |
The available parameters are:
ftp_enable. Should the Joomla! FTP layer be enabled for the new site? It can be
onoroff. The other ftp_* parameters are only required if this is on. Otherwise, they can be left blank. However, the ftp_enable must be defined in thejpi4automation.ini.ftp_host. The FTP host name, without the ftp:// protocol prefix, e.g. ftp.example.com.
ftp_port. The FTP port to connect to, normally it's 21.
ftp_user. The username to use when connecting to the FTP server.
ftp_pass. The password to use when connecting to the FTP server.
ftp_root. The FTP directory where your site has been restored. You can find this out by launching a graphical FTP client, for example FileZilla, finding where kickstart.php is stored and noting down the FTP path shown. This is the path you have to use in this variable.
sitename. The name of the restored Joomla! site. If you don't include it, the old site's parameter will be used.
mailfrom. The email which will appear as the sender of all of the site's emails. If not included, the old site's parameter will be used.
fromname. The sender name for all of the site's emails. If not included, the old site's parameter will be used.
sauser. The numerical Super Administrator user ID for who you want to change his password and/or email. If not defined, no change to the Super Administrator credentials will occur (the old site's login credentials will be still in effect). You can find the numerical ID of the Super Administrator user from Joomla!'s backend, in the User Management page.
sapass1. The Super Administrator password for the new site. If not included, the old site's Super Administrator password will be used.
saemail. The Super Administrator email for the new site. If not included, the old site's Super Administrator email will be used.
tmp_path. The absolute path to the temporary files directory of the restored site. If not included, JPI4 will automatically determine the correct path. If the old site's temporary files path exists and is writable, it will be used in the new site as well. If not, the tmp directory inside the restored site's root will be used.
You can start the path with $SITEROOT, just like in the example above. The $SITEROOT will be automatically replaced with the absolute path to the restored site's root directory.
log_path. The absolute path to the log files directory of the restored site. The same as above holds true, with the exception that the default value is the log directory inside the restored site's root.
In order for the JPI4 restoration to work, only the ftp_host parameter has to exist. Everything else is optional.
Except the two necessary sections above, you can have one
section per backed up database. The names of the sections must be the
same as those listed in the
installation/sql/databases.ini file inside the
backup file. The section regarding the site's main database is always
named [joomla.sql]. A database section looks like this:
[joomla.sql] dbtype=mysql dbhost=localhost dbuser=myuser dbpass=mypass dbname=joomladb prefix=jos_ existing=backup suppressfk=on maxchunk=1048756 maxqueries=1000
The available parameters are divided into two groups: Obligatory and optional. The obligatory ones must appear for each database which is to be restored and are:
dbtype. The database connection type, it can be
mysqlormysqli. If unsure, pelase usemysql.dbhost. The database server host name.
dbuser. The database server user name.
dbpass. The database server password.
dbname. The name of the actual MySQL database to be used for restoration, for example joomla or myaccount_joomla, etc.
prefix. The prefix of the restored database. This is required only for the [joomla.sql] section and can't be left blank. For the other sections it is simply ignored and can be either left blank or not be present at all.
The optional parameters are the fine-tuning options of JPI4:
existing. What to do with any tables already existing in the database. This can be
dropto delete the old tables, orbackupto create backup copies of the existing tables.suppressfk. It can either be
onoroff. When set toon, JPI4 will suppress foreign key checks, so that databases having tables with foreign keys can be restored. It is a good idea to always set to on.maxchunk. JPI4 will read at most this amount of data from the database dump in one go while restoring. This is useful if the restoration times out. The default value, if this option is omitted, is 1048756 (this 1Mb expressed in bytes). Use a lower value if you get timeouts, or a higher value to speed things up.
maxqueries. This is the maximum number of SQL queries JPI4 will execute in a single go while restoring your database. The default value is 1000. If the restoration times out, please lower this to 500 or even 100. Some incredibly slow servers might require an even lower value, e.g. 100, but restoration will be extra slow then.
In order to use Kickstart, you need to upload two files on your site: the archive itself (in ZIP or JPA format) and kickstart.php itself. All you have to do is upload them to the intended server location where your (restored) site will reside.
Kickstart can also be used against plain Joomla! distribution files in ZIP format; instead of uploading a JoomlaPack-generated backup archive you can upload a Joomla! distribution ZIP file and follow the same procedure.
Make sure that any folders in common with your backup file, if they exist, are writable! This is only required if you are restoring over an existing site.
In order to launch the Kickstart wizard, you simply visit the
http:// ,
replacing www.example.com /
mysitefolder /kickstart.php www.example.com with your server's
host name and mysitefolder with whatever
folder you uploaded your files into. If you have uploaded to your
server's root, you should omit both
mysitefolder and its trailing slash.
For example, if you uploaded the files to a folder named joomla and your host name is www.mygreatsite.com, location to put in your browser's address bar is http://www.mygreatsite.com/joomla/kickstart.php . If you uploaded your files to the web server root and the host name is www.mybigsite.com then the location in the address bar should be http://www.mybigsite.com/kickstart.php.
