History: Foo-Installation-Doc-2018

Source of version: 8 (current)

{redirect page="Installation"}

{maketoc title=""}

! Introduction
You don't have to be a web developer or programmer to install Tiki. Tiki has an easy-to-use, wizard-based installer which will do most of the work for you. The rest can be completed from your webhost's control panel. You can also use ((tw:1-click installers)).

If you are a complete novice (or are just not into DIY = do it yourself ) consider using ((tw:Tiki friendly hosts)). Many will complete your Tiki setup you free of charge.

! Before you begin
Before installing Tiki, read the ((Requirements|Requirements and Setup information)) and use the ((Server Check)) tool. Proper planning can ensure a worry-free installation. If you need a webhost for your Tiki, refer to the list of ((tw:Tiki Friendly Hosts)). 

These instructions are intentionally generic, and should apply to most shared host installations. See ((Installation Guides)) for instructions for specific combination of operating system and web servers.

!!# Prerequisites
This guide assumes you have:
* FTP or SSH (shell) access to a webserver (such as Apache) with PHP5
** Typically, you upload the files via a FTP client such as [http://winscp.net/|WinSCP] or [http://filezilla-project.org/|FileZilla].
* access to a MySQL database (should be provided by your webhost)

!Step-by-step installation
!!# Create the database 
Tiki requires a MySQL database.

Many hosts offer a point & click interface to create databases and database users. For example, if your web host has [http://www.cpanel.net|cPanel] you probably can see [http://www.phpmyadmin.net/|phpMyAdmin] in the main menu or a the section labeled __Databases__.

{img type="src" src="img/wiki_up/cpanel_phpmyadmin.png" alt="cPanel image" title="The MySQL and phpMyAdmin applications in cPanel 11"}

Creating a database (and a database user) is a very simple operation. Essentially you will create a blank (empty) database that the Tiki installer will later populate with the correct tables and data.

!!!# The Three steps of database setup
#Create a database.
**You can name the database anything you want, but don't get fancy with the name -- you can use __tiki__. Depending on your web host, your full database in phpMyAdmin may be listed as ''accountname_tiki''.
++__Note__: By default, Tiki uses __UTF-8__ for your database encoding. We strongly encourage you to select "utf8" in the "__collation__" drop-down box in phpmyadmin (or similar), in the field shown in the following image:
++{img src="display1431" link="display1431" width="100%" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}
++If you select a different encoding method, you may need to manually update your __../db/local.php__ file.
++__Tip__: If you plan on having multiple Tiki installations, don't use __tiki__ as the database name. 
**Be sure to record the database name, you will need it later.
#Create a database __user__ (with password).
**Again, don't get fancy with the database username. In fact, you can use the same name that you selected for the database (in step 1).
**Select a __strong__ password. You can easily recover your database username and password if necessary (by reviewing the -+../db/local.php+- file in your Tiki directory.
**Be sure to record the username and password. You will need it later.
#Assign __all__ database permissions to the database user that you created (in step 2).

Congratulations. You now have a database that is ready to use, as well a a database user (and password) with the necessary permissions.

!!# Download Tiki package file
!!!# From the online repository
{TABS(tabs="SVN|GitLab")}

This method requires __(a)__ a server with shell (command line) access and __(b)__ a running SVN instance on this server.

For the SVN part please have a look at the page ((dev:Get-code| Get Code on dev.tiki.org)). On this page and if necessary aswell on the related pages, you find notes about the SVN commands and the particular paths you need to use in the command line to automatically checkout or update the right Tiki version into the intended installation directory (= tikiroot folder).

__Example for a fresh checkout (recommended also for major upgrades)__

__Method 1__
Checking out to a new folder (that you will specify)

{CODE()}
$ svn checkout https://svn.code.sf.net/p/tikiwiki/code/branches/18.x mynewfolder
{CODE}

__Method 2__
Checking out to the current folder (when you created the intended tikiroot already and changed into this directory prior to the checkout):

{CODE()}
$ svn checkout https://svn.code.sf.net/p/tikiwiki/code/branches/18.x .
{CODE}

__Example for a minor update:__

Do not forget to switch into the tikiroot of the Tiki you want to update

{CODE()}
$ svn up
{CODE}
/////
This method requires __(a)__ a server with shell (command line) access and __(b)__ a running GIT instance on this server.

__Example for a fresh checkout (recommended also for major upgrades)__

__Method 1__
Cloning to a new folder (that you will specify)

{CODE()}
$ git clone https://gitlab.com/tikiwiki/tiki.git mynewfolder
{CODE}

__Method 2__
Cloning to the current folder (when you created the intended tikiroot already and changed into this directory prior to the checkout):

{CODE()}
$ git clone https://gitlab.com/tikiwiki/tiki.git .
{CODE}
{TABS}
!!!# From a release file
!!!!# Download and unzip
((Download)) the current version of Tiki to your local computer from [http://tiki.org/download]. 

The full Tiki archive file download is 20-50MB depending on the version and compression (zip, bz2, etc,).

After downloading the Tiki archive file, decompress (unzip) the file to your local PC.

!!!!# Upload to your webhost
Use FTP (or SCP, SFTP, Rsync, SSH, etc) to connect to your webhost.

Once connected, find your web directory. It is often called -+www+- or -+public_html+-. 
__Note__: This directory name may vary, depending on your webhost.

!!!!!# Example 1: Upload all the Tiki files from your PC to your webhost.  
* If you upload the Tiki files to the root of your web directory, Tiki will be accessible directly from the URL: __http://example.org__
*If you have installed (or plan to install) other applications on your webhost, you may consider putting Tiki in its own subdirectory (for example: __http://example.org/tiki/__). Keep in mind that this might mean that you will have to manually edit the file .htaccess to activate the Tiki subdirectory (for example this "RewriteRule ~94~(.+)$  /tiki-index.php?page=$1  ~91~QSA,L~93~" might need to become this "RewriteRule ~94~(.+)$ __/tiki__/tiki-index.php?page=$1 ~91~QSA,L~93~")

!!!!!# Example 2: Upload using lftp
-+lftp -u username ftp.example.com+-
-+lcd /path/to/local/tiki+-
-+cd /path/to/web/tiki+-
-+set ftp:ssl-allow no+-
-+mirror -R ./+-

A ftp testing upload session to an external webhoster needed approximately two hours, and the limitation was the provider's setting. The local internet connection was __not__ saturated.

Time for more coffee? 

!!# Install Tiki

__Start setup.sh, (in the tikiroot):__:
{CODE()}
$ sh setup.sh
{CODE}
For more information on using setup.sh see also the section 1.4.1 Troubleshooting below or run -+sh setup.sh -h+-. In this section we treat only Composer part, which is only applicable when you use an installation from the repository.

To start Composer you have to use the option "c" after starting the setup.sh script:

{CODE()}
$ sh setup.sh
Your choice [c or f]? c
{CODE}
!!!# Run the Tiki installer (tiki-install.php)
Open a web browser to: __http://example.org/tiki-install.php__ (or __http://example.org/tiki/tiki-install.php__ if you installed Tiki in a subdirectory).

{img src="display1435" link="display1435" width="100%" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}

The first page of the Tiki Installer appears. This installer will allow you to:
* Pick a language
* Test your server settings
** If the installer detects that some of your server settings are inadequate, it will suggest changes to comply to the ((Requirements)).
* Enter your database host, name, username, and password. 
+This is the information from the database that you created earlier. You ''__did__'' remember to write it down, right? For non-default port number use syntax "__example.com;port=3307__"
* Create/update the database
** Note:  on osx installations, the mysql socket is a bit different.  In /etc/php.ini, change all instances of  /var/mysql/mysql.sock to /tmp/mysql.sock and then restart the web server
* Set some preferences, such as admin email
* Disable the install script
* and more

Complete each page of the Tiki Installer.

!!!!# Security choices during installation
There are a couple of important security choices during installation as follows:

!!!!!# Secure login
When configuring general settings during installation, there is an option to "Require secure (https) login". It is recommended to select this option so that data sent between the browser and the site server is kept private.

In order to implement secure logins, in addition to selecting this option, you will need a security certificate and a dedicated IP address for your domain. These can be obtained or purchased from your web hosting company or, in the case of the security certificate, from third parties.

!!!!!# Locking in the installer
In the last step of the installer, the installer is locked by default once you click the button to enter your Tiki. There is an option to elect to __not__ lock the installer in that last step of the installation. It is highly recommneded that you lock the installer for any production site. The option is provided for concenience for development sites only. The installer allows a user to change or destroy the site's database through the browser so it is very important to keep it locked once the installation or upgrade is complete.

!!!!# Alternative "Step 5" without tiki-install.php
If you are unable to complete the Tiki Installer, continue with a ((Manual Installation)).

!!!# Log in for the first time
Log in using the login box in the right-hand column.
# Enter this information:
## __user:__ Enter ''admin''
## __pass:__ Enter ''admin''
# Click __login__.

!!!# Change the default password.

Use a strong password. You may want to logout right away, and login again, letting your password manager record your password.

!!!# Congratulations!
It is recommended to create a new user and give him admin privileges instead of regularly using the admin account. You can now explore the interface but you should check the extra steps before to get you started.

!!!# Configure Your Tiki
Please visit ((Initial Configuration)) to explain the recommended next steps, or ((configuration)) for the table of contents related to configuring Tiki. 
!!!# Add new features through post-install Profiles
You can enable a set of settings/permissions/content features in a single action, in order to provide a common feature at your Tiki site (make it multilingual, add freetags, configure it as a collaborative environment, etc.) with a just few clicks using the ((Profile Manager)) from "__Admin > Profiles__".

Read more about it at ((Profiles)).
!! Troubleshootings
!!!# With sh setup.sh, Composer script is not starting
You may have this error message
{CODE()}
Wrong PHP version: phpABC < required PHP version.  A version >= phpXYZ is necessary.
{CODE}

The problem is, that many shared hosting providers keep the setting of the default local PHP version of the shell (command-line) to an outdated PHP version which does not match the PHP requirements of Tiki or of the composer. Alternativ PHP settings in the .htaccess or in the php.ini file or in the user.ini file have no effect to the PHP version in the shell (command line).

However most of these servers have newer PHP versions available in the shell (command line), which can be used alternatively.
For Tiki 16, likely soon backported to Tiki 15, an option is provided that allows composer to be run with an alternative up-to-date PHP version, given that one is available on the particular server.

Another issue to be addressed is that providers have different naming conventions regarding how to distinguish their available PHP versions. To address this issue, the option "-p" is implemented for the setup.sh script to provide the option to manually change the PHP version used by the script:

{CODE()}
$ sh setup.sh -p PHPVERSION
{CODE}

In a first step, the setup.sh script automatically guesses three typically used namings of up-to-date versions, commonly used on many servers and uses the first one that matches:

{CODE()}
php71 php7.1 php7.1-cli
{CODE}

If the script finds one of these, you should get the following message prior to an autostarting composer:

{CODE()}
Wrong PHP version: phpABC < required PHP version.  A version >= phpXYZ is necessary.
Searching for typically named alternative PHP version ...
... correct PHP version phpDEF detected and used
Local PHP version >= required PHP version XYZ - good

Loading composer repositories with package information
Installing dependencies from lock file
(...)
{CODE}

Now you are done. Problem solved.

__But__ if none of these options work out, you will get the following error message:

{CODE()}
Wrong PHP version: phpABC < required PHP version.  A version >= phpXYZ is necessary.
Searching for typically named alternative PHP version ...
... no alternative php version found.
Please provide an alternative PHP version with the -p option.
Example: sh setup.sh -p phpXYZ.
You can use the command-line command 'php[TAB][TAB]' to find out available versions.
{CODE}

This should be self-explanatory. You simply have to use the php command in the shell, followed by twice typing the TAB key without any space or other key and then the Enter. Then the shell (command line) will provide a list of the available PHP versions which you can use (obviously using the naming convention used on the particular server):

Example:
{CODE()}
$ php[TAB][TAB]
php    php-56  php-70  php-71  php-72
{CODE}

How to use this information:
Given the required PHP version would be php 7.1, but your provider uses php 5.3 by default, you simply need to type the following command to start setup.sh with the right PHP version for the composer (in this particular case php-71) ...

{CODE()}
$ sh setup.sh -p php-71
Your choice [c]? c
{CODE}

Then setup.sh will start composer with php 7.1 after the following message:

{CODE()}
Wrong PHP version: phpABC < required PHP version.  A version >= php71 is necessary.
Searching for typically named alternative PHP version ...
... correct PHP version php55 detected and used
Local PHP version >= required PHP version 71 - good
{CODE}

If you know a newer version of php is installed but it is not found by the TAB method above, it means it is not in your PATH environment variable. If you can find its location, you can use the -p option with a full path like:
{CODE()}
$ sh setup.sh -p /opt/rh/rh-php71/root/bin/php
Your choice [c]? c
{CODE}

Now you need only to follow the setup.sh dialog to fix directory permissions (option [f] is reasonably secure works on most average servers. If you need a more secure setting or if your server needed a less restrictive setting (better change the server then), you can use another option. To find out which permission option is best n your server, you can use ((Permission Check)).

You are done now and can go to your website to run the installer.

!!!# File and Folder permissions
If you have file and folder permissions issues, here is the link to resolve them: ((File and folder permissions))

!!!# Tiki installer missing third party software files

{img src="display1433" link="display1433" width="100%" rel="box[g]" imalign="center" desc="Click to expand" align="center" styleimage="border"}

You need to run __sh setup.sh__ from command lines:

{CODE()}
$ sh setup.sh
Your choice [c]? c
{CODE}

! For more information on the Tiki installation process...
__Related pages:__ 
{SPLIT()}
[tiki-view_faq.php?faqId=4|Installation FAQ]
((Installation Guides)) - recipes, tips and detailed knowledge about specific hosting environments
((Migrate to Tiki))
((Move Tiki to a new server))
((Reinstall)) - to point tiki to a new database or re-run an upgrade
---
((Tiki in Ten minutes)) - a recipe for command line installations.
((Fantastico Installation))
((Using SSH)) (for newbies)
((Manual Installation))
((MultiTiki))
{SPLIT}

-=Alias=-
* (alias(Install))
* (alias(How to install))
* (alias(How to install Tiki))
* (alias(How to install TikiWiki))