Download RUNALYZE administration documentation

RUNALYZE administration
documentation
Release 3.0
Hannes Christiansen, Michael Pohl
August 06, 2016
General
1
Frequently Asked Questions
1.1 Error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
3
4
2
Support
2.1 Report a bug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
7
3
Installation instructions for v3.x
3.1 General . . . . . . . . . . . . . .
3.2 Ubuntu/Debian distributions . . .
3.3 Windows . . . . . . . . . . . . .
3.4 Running RUNALYZE on Apache
3.5 Running RUNALYZE on NGINX
.
.
.
.
.
9
9
9
10
10
10
4
Installation instructions for v2.x
4.1 General instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2 Ubuntu/Debian distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 FreeNAS jail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
11
11
11
5
Update instructions for v3.x
5.1 General instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Upgrade from 2.6 to 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
17
17
6
Update instructions for v2.x
6.1 General instructions . .
6.2 Upgrade from 2.5 to 2.6
6.3 Upgrade from 2.4 to 2.5
6.4 Upgrade from 2.3 to 2.4
6.5 Upgrade from 2.2 to 2.3
6.6 Upgrade from 2.1 to 2.2
.
.
.
.
.
.
19
19
19
19
20
20
20
7
Configuration
7.1 Examplary configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 Configuration variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
23
24
8
Templates
8.1 Using your own templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
27
9
Checkout
29
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
i
9.1
9.2
9.3
9.4
9.5
9.6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
29
29
29
30
30
30
10 Contributing
10.1 Issues . . . . . . . . . . . . . . . . . . . . . . . . . .
10.2 Setting up topic branches and generating pull requests
10.3 Pull upstream changes into your fork regularly . . . .
10.4 How to get your pull request accepted . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
31
31
31
32
32
ii
Required tools . . . . . . .
Clone our repository . . . .
Installation of dependencies
Installation of RUNALYZE
Stay up to date . . . . . . .
Further hints . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
RUNALYZE administration documentation, Release 3.0
These docs are for admins hosting an installation of RUNALYZE. If you’re looking for the user docs visit our Help.
Note: RUNALYZE started as one-man-project with only one user and has grown to an app with around 10.000 users
of our official online version. Server requirements and complexity of the app and its configuration grow with the
feature list. Please understand that our main focus is on implementing new features and serving a performant online
version. Therefore, support for local installations is limited.
Missing something in these docs? Contribute at Github or open an issue about what’s missing.
General
1
RUNALYZE administration documentation, Release 3.0
2
General
CHAPTER 1
Frequently Asked Questions
1.1 Error messages
1.1.1 Fatal error: Maximum execution time of 30 seconds exceeded in
Set the max_execution_time in your php.ini file higher than 30 seconds
ini_set(’max_execution_time’, 300); to your index.php or update.php (where it happens).
or
add
If you are trying to update RUNALYZE, try to run the respective update file (you will find the sql-file in
inc/install) manually.
1.1.2 „out of memory“ or „Maximum execution“
Depending on your server settings RUNALYZE may have problems with large files. Especially logbook files can be
large or if the Forerunner is set to “Record a data point every second” these problems may occur. The frequency of
recording can be changed in the settings of the Forerunner.
1.1.3 PHP Parse error: syntax error, unexpected ‘[’
The following error may appear while trying to view an activity:
PHP Parse error: syntax error, unexpected '[' in /runalyze/inc/core/View/Activity/Plot/Series/Pace.ph
Answer:
Your PHP version is too old. RUNALYZE 2.1+ requires at least PHP 5.4. Please update your server or ask your
provider.
Note: We recommend PHP 5.6!
1.1.4 PHP Warning: Missing date.timezone setting
Error message in the error log of the webserver:
PHP Warning:
date(): It is not safe to rely on the system's timezone settings. You are *required* to
Answer: Set the right date.timezone in your php.ini file. E.g. for Germany:
3
RUNALYZE administration documentation, Release 3.0
date.timezone = "Europe/Berlin"
1.1.5 Internal Server Error 500
This is a very inprecise error message. Sometimes there is only a problem with your .htaccess, but in most cases
there is another problem.
Please have a look at your server log, where you will find the exact error message. If you have this problem you should
attach the log to your post.
1.1.6 PHP Fatal error: Class ‘RunalyzePluginPanel_Schuhe’ not found
The following error may appear after updating from v2.1 to v2.2 when opening the plugin’s configuration:
PHP Fatal error: Class 'RunalyzePluginPanel_Schuhe' not found in /runalyze/inc/plugin/class.PluginFac
Answer: You probably copied the new version into your existing runalyze-directory without removing the old files.
You can just delete the folder /plugin/RunalyzePluginPanel_Schuhe/.
1.1.7 MySQL error: Cannot add or update a child row
The following error may appear while trying to update your database:
#1452 - Cannot add or update a child row: a foreign key constraint fails (`runalyze`.`#sql-4a8_39`, C
Answer: From RUNALYZE v2.2 on we are using foreign keys to keep the database consistent. It seems that your table
contains at least one row that should be deleted, for example because the respective activity does not exist anymore.
Please read the exact error message (which constraint fails?), find the faulty row and delete it.
Example: The constraint (activityid) REFERENCES runalyze_training (id) fails while trying to
alter table runalyze_trackdata. You can find the faulty row with:
SELECT runalyze_trackdata.*, runalyze_training.id FROM runalyze_trackdata LEFT JOIN runalyze_training
Remember the shown activityid, delete this row from runalyze_trackdata by hand and try the respective
line from the database update again.
1.2 Common problems
1.2.1 Import/Export is not working
Check that the following directories exist and are writable:
/data/backup-tool/
/data/cache/
/data/import/
/data/log/
4
Chapter 1. Frequently Asked Questions
RUNALYZE administration documentation, Release 3.0
1.2.2 The public activity view is not working
All shared views require mod_rewrite. RUNALYZE comes with a pre-configured .htaccess file in its root
directory. Make sure that the file is there and that mod_rewrite is enabled. If the public activity view is still not
working you may need to set the RewriteBase:
RewriteBase /
You may need to set a special base if your RUNALYZE installation is located in a subdirectory of your domain. If you
access RUNALYZE via yourdomain.com/runalyze/ you may need to use:
RewriteBase /runalyze
1.2.3 My RUNALYZE version is only in english
On Linux (Ubuntu/Debian):
Maybe you are missing the gettext PHP package. Please install the package php-gettext. Don’t forget to restart
your webserver!
1.2.4 Cannot activate my account (no activation mail)
Usually the account should be activated automatically when you host your RUNALYZE installaton locally. If this
fails you have to remove the hash from the activation_hash colum of the user of the _account table in the
database.
1.2. Common problems
5
RUNALYZE administration documentation, Release 3.0
6
Chapter 1. Frequently Asked Questions
CHAPTER 2
Support
Getting support for RUNALYZE is not hard. If you have problems or general questions about the installation, update,
usage of RUNALYZE you can contact us/the community by the following ways
• Forum : You can post your problems there in english or german. This is the best place to put your issues.
• Github : Create a new issue at github.
• Google+ : Post your problem in the google+ community
• Facebook : Post your question/problem on the RUNALYZE wall or write us a private message
2.1 Report a bug
• Github : Create a new issue at github.
7
RUNALYZE administration documentation, Release 3.0
8
Chapter 2. Support
CHAPTER 3
Installation instructions for v3.x
The following instructions are valid only for official RUNALYZE releases starting from version 3.0. If you want to
use our current development version, have a look at our checkout instructions.
In general, RUNALYZE requires at least PHP 5.5.9+ and MySQL 5.0.0+. We encourage you to use the latest MySQL
versions for future releases (5.7).
3.1 General
Since version 3.0 the web directory is the public web directory. We strongly recommend you to use a specific
(sub)domain for your RUNALYZE installation. Otherwise, it’s your responsibility to secure your configuration files
and we cannot guarantee that all parts of RUNALYZE will work as expected.
To install an official release, download the respective *.zip or *.tar.gz file and unpack the archive.
Copy app/config/default_config.yml to data/config.yml and adjust at least the following settings:
database_host: 127.0.0.1
database_prefix: runalyze_
database_port: 3306
database_name: runalyze
database_user: root
database_password: xxx
#
#
#
#
#
#
database hostname or ip (e.g. localhost, 127.0.0.1 ...)
table prefix of the new RUNALYZE installation
port of the database server (normally 3306)
database name
database username
database password
Afterwards open /install in your browser and follow the instructions. This will work only if the database settings
are correct.
3.2 Ubuntu/Debian distributions
Packages: php-gettext libxml2 gettext
You may need to install the corresponding locales to get the translations running: Have a look in less
/usr/share/i18n/SUPPORTED whether the locale is already installed. If not you have to install the locales
on the system(the following example is for the german language):
sudo locale-gen de_DE.UTF-8
sudo service apache2 restart
9
RUNALYZE administration documentation, Release 3.0
3.3 Windows
Warning: We encourage you to use a unix system. We cannot guarantee that RUNALYZE will always be
compatible with a Windows system. You will get the best experience with a unix system.
Warning: The ttbin-Importer will only work with a unix system.
3.4 Running RUNALYZE on Apache
Warning: Required Apache modules - You need to enable mod_rewrite for Apache. On Debian-based systems
you can do this by a2enmod rewrite
Create a new virtual host:
3.5 Running RUNALYZE on NGINX
10
Chapter 3. Installation instructions for v3.x
CHAPTER 4
Installation instructions for v2.x
Warning: These are the old installation instructions for all versions before version 3.0!
The following instructions are valid only for official RUNALYZE releases before version 3. If you want to use our
current development version, have a look at our checkout instructions.
4.1 General instructions
In general, RUNALYZE requires at least PHP 5.4+ and MySQL 5.0.0+. To install an official release, download the
respective *.zip or *.tar.gz file, unpack the archive and open install.php from that directory with your browser.
You need an API-Key for the Garmin Communicator Plugin. You can get it at garmin.com.
You need an API-Key for the OpenWeatherMap weather data. You can get it at openweathermap.org. The standard
free API key can only get current weather information.
4.2 Ubuntu/Debian distributions
Packages: php-gettext libxml2 gettext
You may need to install the corresponding locales to get the translations running: Have a look in less
/usr/share/i18n/SUPPORTED whether the locale is already installed. If not you have to install the locales
on the system(the following example is for the german language):
sudo locale-gen de_DE.UTF-8
sudo service apache2 restart
4.3 FreeNAS jail
4.3.1 1. Create new FreeNAS jail
• VIMAGE: checked
• Everything else: Default
11
RUNALYZE administration documentation, Release 3.0
4.3.2 2. Open a shell, connect to your freenas box and open a shell in the created
jail.
$> jls
$> jexec <name|id> csh
--> list all jails
--> opens a shell in the shell with <name|id>
4.3.3 3. Install required packages (nginx, php, mysql, ...).
$> pkg install nginx php56 php56-extensions mysql56-server php56-mysql php56-mbstring php56-zlib php5
4.3.4 4. Add the following lines to your __/etc/rc.conf__ file
nginx_enable="YES"
php_fpm_enable="YES"
mysql_enable="YES"
4.3.5 5. Configure MySQL:
Create the file __/usr/local/etc/my.conf__
$> ee /usr/local/etc/my.conf
with the following content::
# The MySQL server configuration
[mysqld]
socket = /tmp/mysql.sock
# Don't listen on a TCP/IP port at all.
skip-networking
skip-name-resolve
#Expire binary logs after one day:
expire_logs_days = 1
4.3.6 6. Start mysql-server:
$> service mysql-server start
• Setup basics for mysql and delete default user and tables:
$> mysql_secure_installation
• set a root password, remove anonymous user and test db before reloading privileges table (defaults).
• Now we will create a new sql user called ‘runalyze’ and a database (also ‘runalyze’) where the data is stored:
$> mysql -u root -p
$mysql> CREATE DATABASE runalyze;
$mysql> CREATE USER "runalyze"@"localhost" IDENTIFIED BY "ChangeThisPassword";
$mysql> GRANT ALL PRIVILEGES ON runalyze.* TO "runalyze"@"localhost";
$mysql> FLUSH PRIVILEGES;
$mysql> quit
$> service mysql-server restart
12
Chapter 4. Installation instructions for v2.x
RUNALYZE administration documentation, Release 3.0
4.3.7 7. Ok, now let’s copy the production setup of php-fpm:
$> cp /usr/local/etc/php.ini-production /usr/local/etc/php.ini
Feel free to apply your changes ...
$> ee /usr/local/etc/php.ini
Sample config contains tons of comments and descriptions. Below my changes are listed::
output_buffering = Off
session.save_path = "/tmp"
upload_max_filesize = 20M
post_max_size = 20M
date.timezone = Europe/Vienna
4.3.8 8. PHP - FPM Settings
Create a backup of your php-fpm settings and replace the default config with the following content.:
$> cp /usr/local/etc/php-fpm.conf /usr/local/etc/php-fpm.conf.bak
$> ee /usr/local/etc/php-fpm.conf
[global]
pid = run/php-fpm.pid
[www]
listen = /var/run/phph-fpm.socket
listen.owner = www
listen.group = www
listen.mode = 0666
listen.backlog = -1
listen.allowed_clients = 127.0.0.1
user = www
group = www
pm = dynamic
pm.max_children = 5
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 3
pm.max_requests = 500
env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp
4.3.9 9. Start PHP service:
$> service php-fpm start
4.3. FreeNAS jail
13
RUNALYZE administration documentation, Release 3.0
4.3.10 10. Adjust the nginx.conf file to your needs.
My configuration is listed below:
Note: That i configured another nginx that handles incoming connections from the internet.
So I want to the admin and config file to be accessible from my local network when accessing the server by its internal
IP but don’t want the files to be accessible from outside.
So make sure that you block these files in your configuration!
$> cat /usr/local/etc/nginx/nginx.conf
user www;
worker_processes 2;
events {
worker_connections
}
128;
http {
include mime.types;
default_type application/octet-stream;
sendfile off;
ignore_invalid_headers on;
#server_name_in_redirect off;
server_tokens off;
keepalive_timeout 65;
gzip
gzip_buffers
gzip_comp_level
gzip_http_version
gzip_min_length
gzip_types
gzip_vary
gzip_disable
log_format
#access_log
on;
256 8k;
9;
1.0;
0;
text/css text/javascript text/mathml text/plain text/xml application/x-javascri
on;
"MSIE [1-6]\.(?!.*SV1)";
main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';
logs/access.log
main;
server {
listen 80;
server_name _;
# Prevent Clickjacking
add_header X-Frame-Options "SAMEORIGIN";
#access_log
logs/host.access.log
main;
# Stops the annoying error messages in the logs
location ~* ^/(favicon.ico|robots.txt) {
log_not_found off;
}
14
Chapter 4. Installation instructions for v2.x
RUNALYZE administration documentation, Release 3.0
# Path of your runalyze copy
root /usr/local/www/runalyze;
index index.php;
location / {
client_max_body_size 20M;
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
location ~* \.(?:jpg|jpeg|png|gif|ico|css|js)$ {
expires 10d; add_header Cache-Control public;
}
}
}
}
4.3.11 11. Clone or Download
Clone Runalyze archive or donwload a release zip file to your box and extract it to /usr/local/www/runalyze
$> cd /usr/local/www && fetch https://github.com/Runalyze/Runalyze/releases/download/v2.1.0/runalyze-
4.3.12 12. Access rights
Set the access rights so that your www user is allowed to manipulate the created dir.
$> chown -R www:www /usr/local/www/runalyze
4.3.13 13. Change Perl Path
Change the perl exec path in your configuration.
data/config.php.
You can change it via admin.php or directly edit
Change the path from /usr/bin/perl to /usr/local/bin/perl
4.3.14 14. Install RUNALYZE
Now it is time to install runalyze itself by opening http://<ip-of-you-box>/install.php in your browser
and following the installation routine. If it tells you that perl script wont work don’t mind! Thats caused by a bug in
FreeNAS jails (see: https://bugs.freenas.org/issues/4810). BUT: If you want to be able to import *.fit Files you will
have to apply a little hack.
4.3.15 15. Make the FIT file importer work
Overcome locale errors/warnings of perl: Open the FIT file importer class:
$> ee runalyze/inc/import/filetypes/class.ImporterFiletypeFIT.php
4.3. FreeNAS jail
15
RUNALYZE administration documentation, Release 3.0
Replace the private function readFirstLine() with the following code snippet.
protected function readFirstLine() {
// XXX: Workaround for Perl locale Warnings
//
Lines like the following are ignored silently:
// --- Console log of perl running with undefined locale --// perl: warning: Setting locale failed.
// perl: warning: Please check that your locale settings:
//
LC_ALL = "en_US",
//
LANG = "en_US"
//
are supported and installed on your system.
// perl: warning: Falling back to the standard locale ("C").
// --- end --do {
$FirstLine = stream_get_line($this->Handle, 4096, PHP_EOL);
} while(trim($FirstLine) != 'SUCCESS' && ! feof($this->Handle));
if (feof($this->Handle)) {
//while(($line = stream_get_line($this->Handle, 4096, PHP_EOL)) != false && !feof($this->Hand
//
$FirstLine .= $line;
fclose($this->Handle);
unlink($this->Filename);
throw new RuntimeException('Reading *.fit-file failed. First line was "'.$FirstLine.'".');
}
}
16
Chapter 4. Installation instructions for v2.x
CHAPTER 5
Update instructions for v3.x
5.1 General instructions
• RUNALYZE follows semantic versioning.
• If not stated otherwise, patch updates do not require any further adjustments. Just copy the files into your
working directory.
• If not stated otherwise, major and minor updates require specific adjustments. You have to follow the update
process for each minor version. We can’t guarantee that the latest version will contain all required files for an
update to a previous version.
• Execute the update via cli if you have big installations or a slow server.
Warning: Never ever forget to make a backup before updating or changing your RUNALYZE installation. (You
break it - you fix it)
5.2 Upgrade from 2.6 to 3.0
Since version 3.0, RUNALYZE is based on Symfony. This causes some major changes, especially under the hood, but
will simplify a lot of things in the future.
1. Purge your runalyze/ directory except for the data/ directory and extract the downloaded archive of v3.0.
2. Create an empty directory data/sessions.
3. Make sure that data/sessions, var/cache and var/logs are writable.
4. Copy app/config/default_config.yml to data/config.yml and adjust the settings to your
needs. These are mainly the settings from your data/config.php in a new format, see configuration.
You can delete your data/config.php afterwards.
5. The new web/ directory will be used for all page requests. We strongly recommend you to use an individual
(sub)domain for your installation and let it point directly to web/. There’s an .htaccess in the root directory
that should forward all requests to web/ otherwise, but it’s your responsibility that nobody can access your
data/config.yml.
17
RUNALYZE administration documentation, Release 3.0
18
Chapter 5. Update instructions for v3.x
CHAPTER 6
Update instructions for v2.x
6.1 General instructions
• RUNALYZE follows semantic versioning.
• If not stated otherwise, patch updates do not require any further adjustments. Just copy the files into your
working directory.
• If not stated otherwise, major and minor updates require specific adjustments. You have to follow the update
process for each minor version. We can’t guarantee that the latest version will contain all required files for an
update to a previous version.
• Execute the update via cli if you have big installations or a slow server.
• Instead of loading a specific update file via update.php you can import the respective
inc/install/*.sql manually.
• From v2.4 on, all installation specific files are in data/. Take care that you don’t overwrite this directory.
Warning: Never ever forget to make a backup before updating or changing your RUNALYZE installation. (You
break it - you fix it)
6.2 Upgrade from 2.5 to 2.6
1. Purge your runalyze/ directory except for the data/ directory and extract the downloaded archive of v2.6.
2. Open runalyze/update.php in your browser and update from v2.5 to v2.6.
3. Done! Really! No further steps are necessary! ;)
6.3 Upgrade from 2.4 to 2.5
1. Purge your runalyze/ directory except for the data/ directory and extract the downloaded archive of v2.5.
2. Open runalyze/update.php in your browser and update from v2.4 to v2.5.
Note: The following step is an optional enhancement. Skip this step if you cannot or do not want to get a working
spatialite lib.
19
RUNALYZE administration documentation, Release 3.0
3. We use a sqlite3 database for the timezone recognization. You need the packages spatialite-bin and
php5-sqlite installed on your system.
You also need to download http://cdn.runalyze.com/update/timezone.sqlite and place that
file into your data directory.
In addition, you have to edit your php.ini and make sure that
sqlite3.extension_dir is set correctly. (wherever mod_spatialite is located)
4. Execute the refactor-timezone.php script. (no database connection has to be set)
5. Everything should be fine now. Please login into you account. You may have to change your timezone in the
account settings.
6.4 Upgrade from 2.3 to 2.4
1. Purge your runalyze/ directory except for config.php and extract the downloaded archive of v2.4.
2. Move config.php to data/config.php
3. Add $port = 3306; to data/config.php (3306 is the default mysql-port)
4. Open runalyze/update.php in your browser and update from v2.3 to v2.4.
5. You should run build/global.routefix.php (Set the database connection in the file) (To access this
script via browser just rename the .htaccess file in the build/ directory. Don’t forget to rename the file
afterwards)
6. You should run now refactor-night.php (no database connection has to be set)
7. Maybe you have to adjust the permissions for data/*
Note: If have local srtm files you should move them from inc/data/gps/srtm to data/srtm
6.5 Upgrade from 2.2 to 2.3
1. Purge your runalyze/ directory except for config.php and extract the downloaded archive of v2.3.
2. Open runalyze/update.php in your browser and update from v2.2 to v2.3.
3. Insert your database connection in refactor-geohash.php and adjust the other settings, e.g. the prefix if
it’s not runalyze_.
4. Run refactor-geohash.php via command line or browser. (We recommend to run this script via command line, because of long execution times)
5. Remember to remove your credentials from refactor-geohash.php afterwards.
6. We haved moved the Perl path setting to your config.php (or via admin.php). You may have to changed this path
6.6 Upgrade from 2.1 to 2.2
Note: Please directly update from 2.1 to 2.2.1 to avoid any known problems with upgrading from single-user installations.
20
Chapter 6. Update instructions for v2.x
RUNALYZE administration documentation, Release 3.0
From v2.2+ RUNALYZE does not support single-user installations without account anymore. You can skip this section
if your installation does use an account.
6.6.1 Upgrade single-user installation
1. Edit your config.php and set USER_MUST_LOGIN to true (this definition is ignored from v2.2+ anyway):
define('USER_MUST_LOGIN', true);
2. Open runalyze/login.php in your browser and register a new account
3. Purge your runalyze/ directory except for config.php and extract the downloaded archive of v2.2.
4. Attention! Instead of importing inc/install/switch-accountid-to-1.sql to your database use
this one.
5. Continue with step 2 of the “Upgrade multi-user installation”
6.6.2 Upgrade multi-user installation
1. Purge your runalyze/ directory except for config.php and extract the downloaded archive of v2.2.
2. We highly recommend using InnoDB as storage engine for your database.
Please import
inc/install/innodb.sql to your database (you may have problems with SET GLOBAL statements,
just leave them out).
3. Open runalyze/update.php in your browser and update from v2.1 to v2.2. You can ignore errors like the
following if you don’t want to use InnoDB as storange engine:
SQLSTATE[HY000]: General error: 1005 Can't create table 'd03e141b.#sql-592_6c53c5' (errno: 150)
4. For this update of RUNALYZE you have to run another refactor script. Insert your database connection in
refactor-equipment.php and adjust the other settings, e.g. the prefix if it’s not runalyze_..
5. If you don’t want or can’t use InnoDB as your storage engine you have to adjust CHECK_INNODB to:
define('CHECK_INNODB', false);
6. Run refactor-equipment.php via command line or browser.
7. Remember to remove your credentials from refactor-equipment.php afterwards.
6.6.3 Common problems
** Error in query (1193): Unknown system variable .... during importing innodb.sql
Comment or remove the “SET GLOBAL” lines and try it again
6.6. Upgrade from 2.1 to 2.2
21
RUNALYZE administration documentation, Release 3.0
22
Chapter 6. Update instructions for v2.x
CHAPTER 7
Configuration
RUNALYZE
needs
at
least
database
parameters
to
work.
Copying
a
app/config/default_config.yml to data/config.yml is part of the Installation process.
default
All parameters are optional.
If they are not in your custom data/config.yml default values from
app/config/default_config.yml will be used. Still, we recommend to include all parameters in your custom configuration.
Note: You need to clear your cache (var/cache/prod/ in general) for the changes to take effect.
7.1 Examplary configuration
parameters:
locale: en
database_host: 127.0.0.1
database_prefix: runalyze_
database_port: 3306
database_name: runalyze
database_user: root
database_password:
secret: please_change_this_secret
update_disabled: no
user_can_register: true
user_cant_login: false
user_disable_account_activation: false
maintenance: false
garmin_api_key:
openweathermap_api_key:
nokia_here_appid:
nokia_here_token:
geonames_username:
perl_path:
ttbin_path:
sqlite_mod_spatialite:
mail_sender:
mail_name:
smtp_host:
smtp_port:
smtp_security:
23
RUNALYZE administration documentation, Release 3.0
smtp_username:
smtp_password:
7.2 Configuration variables
locale Default language, see data_config_lang.php for available languages
database_host Host name of your database, localhost or 127.0.0.1 for local installations, otherwise specific
to your hoster
database_prefix Prefix for all RUNALYZE tables in your database, by default runalyze_. Changing this value is
only needed if you want to keep multiple installations in one database.
database_port Port number for database connection, defaults to 3306
database_name Name of your database, you need to creat it if it does not already exist
database_user Username for database connection
database_password Password for database connection
secret Installation specific secret that is used for hashing. Just use your own string.
update_disabled Setting this parameter to yes will disable all pages for installing and updating RUNALYZE to
protect public installations. Updates via console are still possible. This parameter defaults to no such that the
installation is possible.
user_can_register Flag if users can register. Set to false to disable registration form.
user_cant_login Flag if users can login. Set to true to disable login form (e.g. while updating your installation).
user_disable_account_activation Flag if accounts need to be activated. Set to false to automatically activate accounts
after registration.
maintenance Set to True to enable maintenance mode. Only updater and installer will work during maintenance
mode.
garmin_api_key Api key for GarminCommunicator, required to directly import activities from a connected Garmin
device
openweathermap_api_key Api key for openweathermap.org, required to load weather data
nokia_here_appid App id for HERE access, see <https://developer.here.com/>_, required to use HERE maps
nokia_here_token Token for HERE access
geonames_username Username for geonames.org, used for elevation correction if no local srtm files are available
perl_path Path
to
your
perl
binary,
usually
C:\[...]\xampp\perl\bin\perl on Windows.
/usr/bin/perl
or
something
like
ttbin_path Path to ttbin converter that is required for reading binary ttbin files. A compiled version is located under
call/perl/ttbincnv but you may need to compile it for your os manually, see ryanbinns/ttwach
sqlite_mod_spatialite Name of SQLite spatialite extension, usually libspatialite.so.5. This extension is
required if you want to use data/timezone.sqlite for time zone lookups of activities based on their
coordinates.
mail_sender Mail adress that will be used as sender for outgoing mails, [email protected] will be used if this
value is empty.
mail_name Name that will be used as sender for outgoing mails
24
Chapter 7. Configuration
RUNALYZE administration documentation, Release 3.0
smtp_host Host for smtp server
smtp_port Port for smtp server
smtp_security Security setting, set to ssl or tls if you wish to use the encryption
smtp_username Password for smtp server
smtp_password Password for smtp server
7.2. Configuration variables
25
RUNALYZE administration documentation, Release 3.0
26
Chapter 7. Configuration
CHAPTER 8
Templates
RUNALYZE is (from v3.0 onwards) based on Symfony and uses Twig as template engine. All app-specific templates
are located under app/Resources/views.
8.1 Using your own templates
There are situations where you may want to adjust some of the templates, e.g. to provide additional information on the
login page. To achieve this you can put your own template into data/views. The app will preferably uses templates
from this directory.
Note: data does only contain installation specific files such as your configuration and must not be emptied/replaced
when updating RUNALYZE to keep your settings.
27
RUNALYZE administration documentation, Release 3.0
28
Chapter 8. Templates
CHAPTER 9
Checkout
RUNALYZE is hosted on GitHub. If you want to contribute to RUNALYZE or want to be up to date and use our
current dev version you need to maintain a local checkout of our git repository. GitHub offers a good tutorial How to
set up Git.
9.1 Required tools
Whereas our official release contains all required dependencies, developers and users of our dev version need to install
them themselves.
• composer
• npm
• bower: will be installed via npm
• gulp: will be installed via npm
9.2 Clone our repository
Having installed all required tools you can clone our repository. Open a terminal, switch to the directory where your
copy of RUNALYZE should be located and type the following:
git clone https://github.com/Runalyze/Runalyze.git
This creates a new directory runalyze with all contents from our repository. If you want to contribute to RUNALYZE you should fork our repository. In that case you’ll have to clone RUNALYZE via:
git clone https://github.com/<your-github-name>/Runalyze.git
9.3 Installation of dependencies
To install all current dependencies, open a terminal, switch to your RUNALYZE directory and type the following:
composer install --prefer-dist
npm install
gulp
You may need to install gulp-cli globally: npm install -g gulpjs/gulp-cli
29
RUNALYZE administration documentation, Release 3.0
9.4 Installation of RUNALYZE
Now you can continue with the default installation of RUNALYZE, see Installation instructions for v3.x.
9.5 Stay up to date
You can use git pull to pull recent changes from our master branch to your local checkout. You may need to run
composer update, npm update and gulp to update all dependencies.
9.6 Further hints
• Adjust web/.htaccess to use web/app_dev.php instead of web/app.php if you want to use the dev
environment.
• You may need to adjust web/app_dev.php if some You are not allowed to access this file. message appears.
• Clear var/cache/prod/ (or var/cache/dev/) to clear the cache.
30
Chapter 9. Checkout
CHAPTER 10
Contributing
Before you do anything else, signup if you haven’t and login on GitHub to fork our GitHub project. Now you can
clone your fork locally:
git clone [email protected]:<your-github-name>/Runalyze.git
This creates a new directory runalyze with all contents from our repository. Please have a look at our Checkout
tutorial for further instructions to get that fork running.
10.1 Issues
The list of outstanding feature requests and bugs can be found on our on our GitHub issue tracker. Pick an unassigned
issue that you think you can accomplish and add a comment that you are attempting to do it. Feel free to propose
issues that are not described!
10.2 Setting up topic branches and generating pull requests
It’s best practice to submit your contribution as pull request on GitHub. To separate things, please create a “topic
branch” for each feature or patch you are working on. While individual commits allow you control over how small
individual changes are made to the code, branches are a great way to group a set of commits all related to one feature
together, or to isolate different efforts when you might be working on multiple topics at the same time.
While it takes some experience to get the right feel about how to break up commits, a topic branch should be limited
in scope to a single issue as submitted to an issue tracker.
Also since GitHub pegs and syncs a pull request to a specific branch, it is the ONLY way that you can submit more
than one fix at a time. If you submit a pull from your develop branch, you can’t make any more commits to your
develop without those getting added to the pull.
To create a topic branch, its easiest to use the convenient -b argument to git checkout:
git checkout -b patch/for-xyz
Switched to a new branch 'patch/for-xyz'
You should use a verbose enough name for your branch so it is clear what it is about. Now you can commit your
changes and regularly merge in the upstream master as described below.
When you are ready to generate a pull request, either for preliminary review, or for consideration of merging into the
project you must first push your local topic branch back up to GitHub:
31
RUNALYZE administration documentation, Release 3.0
git push origin patch/for-xyz
Now when you go to your fork on GitHub, you will see this branch listed under the “Source” tab where it says “Switch
Branches”. Go ahead and select your topic branch from this list, and then click the “Pull request” button.
Here you can add a comment about your branch. If this in response to a submitted issue, it is good to put a link to
that issue in this initial comment. The repo managers will be notified of your pull request and it will be reviewed
(see below for best practices). Note that you can continue to add commits to your topic branch (and push them up to
GitHub) either if you see something that needs changing, or in response to a reviewer’s comments. If a reviewer asks
for changes, you do not need to close the pull and reissue it after making changes. Just make the changes locally, push
them to GitHub, then add a comment to the discussion section of the pull request.
10.3 Pull upstream changes into your fork regularly
It is critical that you pull upstream changes from master into your fork on a regular basis. Nothing is worse than
putting in a days of hard work into a pull request only to have it rejected because it has diverged too far from develop.
To pull in upstream changes:
git remote add upstream https://github.com/Runalyze/Runalyze.git
git fetch upstream master
Check the log to be sure that you actually want the changes, before merging:
git log upstream/master
Then merge the changes that you fetched:
git merge upstream/master
For more info, see http://help.github.com/fork-a-repo/
10.4 How to get your pull request accepted
We want your submission. But we also want to provide a stable experience for our users and the community. Follow
these rules and you should succeed without a problem!
10.4.1 Run the tests!
Before you submit a pull request, please run all unit tests via:
./vendor/bin/phpunit -c tests/config.xml
Travis CI will run these tests as well but it’s bad practice to wait for these results as you can run all tests locally. You
may need to create (or update) a test database if you haven’t done so:
mysql -uroot -e 'SET @@global.sql_mode = TRADITIONAL; CREATE DATABASE runalyze_test; CREATE DATABASE
mysql runalyze_unittest < inc/install/structure.sql
32
Chapter 10. Contributing
RUNALYZE administration documentation, Release 3.0
10.4.2 If you add code you need to add tests!
Please add test cases if you have added new classes or methods. Code without tests is undependable.
Also, keep your tests as simple as possible. Complex tests end up requiring their own tests. We would rather see
duplicated assertions across test methods then cunning utility methods that magically determine which assertions are
needed at a particular stage. Remember: Explicit is better than implicit.
10.4.3 Follow our coding guidelines
Your code should follow PSR-1 and PSR-2. In addition, please follow some general guidelines for clean code. This
includes for example:
• loose coupling: different classes should know as less as possible about each other
• high cohesion: methods and properties of a single class should belong to each other
• single responsibility: a class should have one and only one reason to charge (the same applies for methods)
• small classes: there must be a really good reason if a class exceeds 200 lines
• short methods: there must be a really good reason if a method exceeds 20 lines
• descriptive names: variable and method names should be descriptive, there is no need to use funky abbreviations
10.4. How to get your pull request accepted
33