You are here: Home / Debian GNU/Linux / Web applications / Statistics / Install Piwik web analytics tool on Debian

Install Piwik web analytics tool on Debian

by Pierre-Yves Landuré last modified Jan 22, 2019 09:03

Piwik is a Web access statistics free software willing to be an alternative to Google Analytics. This howto help you to install it on Debian.

This how-to is tested on :

  • Debian 6.0 Squeeze
  • Debian 7.0 Wheezy

This how-to is tested with these versions of Piwik :

  • 1.8
  • 1.11.1


This how-to needs :


Provide the domain name where the software will be available:


Provide the MySQL server host:


If the MySQL server is not local, the mysql-tools script will try to connect with MySQL client, or in case of connection failure, through SSH.

Provide the name of the SSL certificate to use (created by following Create a SSL / TLS certificate on Debian) (optionnal, recommended):



Compute the installation path:


Compute the cache path:


Make sure that the parent folder exists :

command mkdir --parent "$(command dirname "${INSTALL_PATH}")"

Environment preparation

Install the needed software :

command apt-get install apg unzip php5-mysql php5-gd php5-cli

Adjust PHP configuration to the application needs :

command php-tools --for="piwik" --set "memory_limit" "128M"
command php-tools --for="piwik" --set "suhosin.request.max_value_length" "2048"
command php-tools --for="piwik" --set "suhosin.get.max_value_length" "2048"

Reload PHP configuration :

test -e '/etc/init.d/php5-fpm' && command service 'php5-fpm' 'restart'
test -e '/etc/init.d/apache2' && command service 'apache2' 'force-reload'

Application installation

Download application latest version :

command wget "" \

Extract the archive :

command unzip -d "/tmp" "/tmp/" "piwik/*"

Delete the archive :

command rm "/tmp/"

Move the source folder to the install path :

command mv "/tmp/piwik/" "${INSTALL_PATH}"

Allow the application to update its configuration files :

command chown -R www-data:www-data "${INSTALL_PATH}/config"

Setup the HTTP server virtual host :

if [ -n "${SSL_KEY_NAME}" -a -e "/etc/ssl/private/${SSL_KEY_NAME}.key" ]; then
  command a2tools --ssl="${SSL_KEY_NAME}" "${DOMAIN}" "${INSTALL_PATH}"
command a2tools "${DOMAIN}" "${INSTALL_PATH}"

The application is now available on the specified domain name with HTTP and HTTPS protocols if possible.

Conformity with LSB

Move cache folders to fit Linux Standard Base :

command mkdir --parent "$(command dirname "${CACHE_PATH}")"
if [ -d "${INSTALL_PATH}/tmp" ]; then command mv "${INSTALL_PATH}/tmp" "${CACHE_PATH}" command chown -R www-data:www-data "${CACHE_PATH}" command ln -s "${CACHE_PATH}" "${INSTALL_PATH}/tmp" fi

Database creation

Create the database :

command mysql-tools --server="${MYSQL_HOST}" --with-ssh \
--auto-hosts --db-prefix="piwik" --create "${DOMAIN}"

Write down the provided informations.

Initial setup

Start the tool initial setup by browsing the URL provided by :

echo "http://${DOMAIN}/"

Setup the application to use the previously created database.

Important : In order to harden security against SQL injection attacks, use a random table prefix such as the one generated by :

echo "Table prefix for Piwik : $(command apg -q -a 0 -n 1 -M NCL)_"

Create a random password for the administration account :

echo "Admin account password : '$(command apg -q -a 0 -n 1 -M NCL)'"

Hardening security

One the application correctly configured, harden the security by restricting write access to config folder :

command chown -R root:root "${INSTALL_PATH}/config"

Advanced setup

Most of the following configurations need the "[General]" section in the configuration file. Make sure it is the case :

if [ -z "$(command grep "[General]" "${INSTALL_PATH}/config/config.ini.php")" ]; then
  command echo "
[General]" >> "${INSTALL_PATH}/config/config.ini.php"

Datas auto-archiving

If the watched sites generate lots of traffic, it is best to setup regular data archiving for usage in the tool web user interface.

Setup the auto-archiving script in the cron.hourly folder in order for it to be run each hour :

command touch "/var/log/piwik-archive-${DOMAIN}.log"
command chown www-data:adm "/var/log/piwik-archive-${DOMAIN}.log"
CLEAN_DOMAIN="$(echo "${DOMAIN}" | command tr '.' '-')" echo -e "# Hourly archiving for ${DOMAIN}. 0 * * * * www-data test -f ${INSTALL_PATH}/console -a -x /usr/bin/php5 && /usr/bin/php5 ${INSTALL_PATH}/console core:archive --url='http://${DOMAIN}' > '/var/log/piwik-archive-${DOMAIN}.log'" \ > "/etc/cron.d/${CLEAN_DOMAIN}" command service 'cron' 'reload'

Check that the archiving script is working :

su www-data -c "/bin/sh ${INSTALL_PATH}/misc/cron/"

Disabling the Web user interface archiving

If the watched sites generate lots of traffic, it is recommended to disable the data archiving when a user use the Web interface :

command sed -i -e '/\[General\]/a\
time_before_archive_considered_outdated = 3600 \
enable_browser_archiving_triggering = false' \

Force HTTPS usage for login

If possible (HTTPS access working), force the use of HTTPS protocol for users login :

command sed -i -e '/\[General\]/a\
force_ssl = 1' \

Reverse proxy usage

If you use a reverse proxy, setup the to to fetch the visitors IP address in XForwardedFor HTTP header :

command sed -i -e '/\[General\]/a\
proxy_client_headers[] = "HTTP_X_FORWARDED_FOR"' \

An other way to do this is if you use a Apache 2 server is to use the setup described by Get the real IP address of a visitor accessing to a Apache 2 server behind a reverse proxy.

If the reverse proxy has working HTTPS support, tell the application to use it when needed:

command sed -i -e '/\[General\]/a\
assume_secure_protocol = 1' \


Backup the installation with Backup Manager (see Install and setup Backup Manager on Debian) :

command backup-manager-tools add "${INSTALL_PATH}"

Don't forget to backup the database (see Install and setup MySQL on Debian)

Software upgrade

Provide the application domain name :


Compute the installation path :


Clean-up the path :

INSTALL_PATH="$(echo "${INSTALL_PATH}" | sed -e 's|/$||g')"

Download the tool latest version :

command wget '' \

Extract the archive :

command unzip -d "/tmp" "/tmp/" "piwik/*"

Get the previous installation data :

command cp -a "${INSTALL_PATH}/config/config.ini.php" "/tmp/piwik/config/"
command rm -r "/tmp/piwik/tmp"
command cp -a "${INSTALL_PATH}/tmp" "/tmp/piwik/tmp"

Backup the obsolete installation :

command mv "${INSTALL_PATH}" "${INSTALL_PATH}.old"

Install the new version :

command mv "/tmp/piwik" "${INSTALL_PATH}"

Upgrade the database :

if [[ -e "${INSTALL_PATH}/console" ]]; then
command su www-data -c "command php '${INSTALL_PATH}/console' core:update"
command su www-data -c "command php '${INSTALL_PATH}/index.php' -- 'module=CoreUpdater'"

The application is no up-to-date. Empty the PHP cache :

test -e '/etc/init.d/php5-fpm' && command service 'php5-fpm' 'restart'
test -e '/etc/init.d/apache2' && command service 'apache2' 'force-reload'

Check that everything work, and delete the downloaded file and the previous installation backup :

command rm "/tmp/"
command rm -r "${INSTALL_PATH}.old"