Difference between revisions of "CDash:Installation"

From KitwarePublic
Jump to: navigation, search
(GIT Development version)
(Stable Release)
 
(12 intermediate revisions by the same user not shown)
Line 4: Line 4:
 
   
 
   
 
== System Requirements ==
 
== System Requirements ==
* Apache
+
 
* SQL database
+
CDash requires:
** MySQL database (5.x and higher)
+
* A web server (Apache, NGINX, IIS) with PHP (5.5.9+) and SSL enabled.
** PostgreSQL database (8.3 and higher)
+
* Access to a MySQL (5.x+) or PostgreSQL (8.3+) database server.
* PHP (5.3 and higher)
+
 
* XSL module for PHP
+
PHP needs to have the following modules enabled:
* cURL module for PHP (for site statistics)
+
* bcmath
* GD module for PHP (for regression tests)
+
* cURL (for site statistics)
* MySQL or PostgreSQL PDO module for PHP
+
* GD (for regression tests)
 +
* mbstring
 +
* pdo-mysql or pdo-postgresql
 +
* XSL
  
 
== Downloading CDash ==
 
== Downloading CDash ==
  
The '''current stable release of CDash is 2.2.3''' you can either download it as a zip archive
+
=== Stable Release ===
* [http://www.cdash.org/wp-content/uploads/2014/11/CDash-2-2-3.zip CDash-2.2.3.zip]
+
The '''current stable release of CDash is 2.6.0''' you can either download it as a zip archive
* or from the [https://github.com/Kitware/CDash.git GIT] repository 'release' branch:
+
* [https://github.com/Kitware/CDash/archive/v2.6.0.zip CDash-2.6.0.zip]
 +
* or as a tag from the [https://github.com/Kitware/CDash.git git repository]:
 
   git clone https://github.com/Kitware/CDash.git
 
   git clone https://github.com/Kitware/CDash.git
    
+
   git checkout v2.6.0-prebuilt
=== GIT Development version ===
 
  
CDash is available from the development [https://github.com/Kitware/CDash.git GIT] repository. Either extract the code into your web server tree, or another directory which will later be copied to the web server:
+
==== Previous versions of CDash ====
 +
* '''2.4''': [http://public.kitware.com/Wiki/File:CDash-2-4-0.zip CDash-2.4.0.zip] or git checkout v2.4.0
 +
* '''2.2''': [http://www.cdash.org/download/CDash-2.2.2.zip CDash-2.0.2.zip] or git checkout Release-2-2-2
 +
* '''2.0''': [http://www.cdash.org/download/CDash-2.0.2.zip CDash-2.0.2.zip] or git checkout Release-2-0-2
 +
* '''1.8''': [http://www.cdash.org/download/CDash-1.8.2.zip CDash-1.8.2.zip] or git checkout Release-1-8-2
 +
* '''1.6''': [http://www.cdash.org/download/CDash-1.6.4.zip CDash-1.6.4.zip] or git checkout Release-1-6-4
 +
* '''1.4''': [http://www.cdash.org/download/CDash-1.4.1.zip CDash-1.4.2.zip] or git checkout Release-1-4-2
 +
* '''1.2''': [http://www.cdash.org/download/CDash-1.2.1.zip CDash-1.2.1.zip] or git checkout Release-1-2-1
 +
* '''1.0''': [http://www.cdash.org/download/CDash-1.0.zip CDash-1.0.zip] or git checkout Release-1-0-2
 +
* '''0.8''': [http://www.cdash.org/download/CDash-0.8.zip CDash-0.8.zip] or git checkout Release-0-8
  
cd /srv/www/htdocs
+
=== GIT Development version ===
git clone https://github.com/Kitware/CDash.git CDash
 
git checkout prebuilt
 
  
=== Previous versions of CDash ===
+
CDash uses [https://getcomposer.org/ composer] and [https://www.npmjs.com/ npm] to manage its 3rd party dependencies.
* '''2.0''': [http://www.cdash.org/download/CDash-2.0.2.zip CDash-2.0.2.zip] or svn co https://www.kitware.com/svn/CDash/Release-2-0 CDash
 
* '''1.8''': [http://www.cdash.org/download/CDash-1.8.2.zip CDash-1.8.2.zip] or svn co https://www.kitware.com/svn/CDash/Release-1-8 CDash
 
* '''1.6''': [http://www.cdash.org/download/CDash-1.6.4.zip CDash-1.6.4.zip] or svn co https://www.kitware.com/svn/CDash/Release-1-6 CDash
 
* '''1.4''': [http://www.cdash.org/download/CDash-1.4.1.zip CDash-1.4.1.zip] or svn co https://www.kitware.com/svn/CDash/Release-1-4 CDash
 
* '''1.2''': [http://www.cdash.org/download/CDash-1.2.1.zip CDash-1.2.1.zip] or svn co https://www.kitware.com/svn/CDash/Release-1-2 CDash
 
* '''1.0''': [http://www.cdash.org/download/CDash-1.0.zip CDash-1.0.zip] or svn co https://www.kitware.com/svn/CDash/Release-1-0 CDash
 
* '''0.8''': [http://www.cdash.org/download/CDash-0.8.zip CDash-0.8.zip] or svn co https://www.kitware.com/svn/CDash/Release-0-8 CDash
 
  
== Configuration ==
+
We provide two developments branches, <code>master</code> and <code>prebuilt</code>. If you're working with the <code>master</code> branch, then you have to run composer & npm yourselfThe <code>prebuilt</code> branch has these dependencies already downloaded for you.
The system configuration is stored in <tt>.../CDash/config/config.php</tt>, however it's recommended to create a '''config.local.php''' in the same directory that contains only the variables you wish to changeDoing so will prevent any changes you make from being overwritten when CDash is upgraded and config.php is re-created.
 
  
Please note that CDash will read the config.php file first, and then config.local.php.  Any variables that are changed in config.local.php will take precedence.
+
==== master ====
  
'''WARNING: If creating the config.local.php from config.php make sure you DELETE any text after the 'DO NOT EDIT AFTER THIS LINE' otherwise your configuration file will be referencing each otherIdeally config.local.php should contain ONLY the variables you have modified.'''
+
Use the <code>master</code> branch if you'd like to modify CDash or contribute to its development.
 +
git clone https://github.com/Kitware/CDash.git CDash
 +
git checkout master
 +
curl -sS https://getcomposer.org/installer | php  
 +
php composer.phar install
 +
  npm install
 +
node_modules/.bin/gulp
  
=== SQL Database ===
+
==== prebuilt ====
If you are running the MySQL database on the same server as the Apache web server the defaults should work with no changes:
 
  
// Hostname of the MySQL database
+
The <code>prebuilt</code> branch is a good choice if you'd like to use new features in CDash on a production server.
$CDASH_DB_HOST = 'localhost';
+
  git clone https://github.com/Kitware/CDash.git CDash
+
  git checkout prebuilt
// Login for MySQL database access
 
$CDASH_DB_LOGIN = 'root';
 
 
// Password for MySQL database access
 
$CDASH_DB_PASS = '';
 
 
// Name of the MySQL database
 
$CDASH_DB_NAME = 'cdash';
 
 
 
If your MySQL (>= v5) server is set to ''strict'' mode, CDash will not work! The reason is that in strict mode, integer columns will not accept the empty string "" as 0 (zero). "" is what the CDash forms currently return for unchecked checkboxes. You'll have to remove the setting <code>STRICT_TRANS_TABLES</code> from the global sql mode parameter. You can query the current setting like this: <code>SELECT @@global.sql_mode;</code>
 
 
 
For more information and more specific settings see the [http://dev.mysql.com/doc/refman/5.0/en/server-sql-mode.html MySQL sql mode documentation].
 
 
 
If you have just installed MySQL don't forget to start it:
 
 
 
rcmysql start
 
 
 
=== Ubuntu Dependencies ===
 
 
 
Here is a list of packages required on Ubuntu 12.04:
 
sudo apt-get install apache2 mysql-server php5 php5-mysql php5-xsl php5-curl php5-gd
 
 
 
Make sure your apache2 configuration pulls in libapache2-mod-php5 and NOT libapache2-mod-php5filter as this will cause PUT requests to fail and you will not be able to submit anything to your dashboard.
 
 
 
=== PostgreSQL Database ===
 
If you are running the PostgreSQL database read the previous MySQL section about configuring the database access.
 
You will also need to tell CDash to use PostgreSQL driver:
 
 
 
  // Database type (empty means mysql)
 
  $CDASH_DB_TYPE = 'pgsql';
 
 
 
Here is list of packages necessary on ubuntu
 
 
 
  sudo apt-get install php-pear
 
  sudo pecl install pdo
 
  sudo apt-get install php5-dev
 
  sudo pecl install pdo
 
  sudo pecl install pdo_pgsql
 
 
 
=== Email ===
 
You should probably edit the default email addresses:
 
 
 
// Default from email
 
$CDASH_EMAILADMIN = 'admin@cdash.org';
 
$CDASH_EMAIL_FROM = 'admin@cdash.org';
 
$CDASH_EMAIL_REPLY = 'noreply@cdash.org';
 
 
 
=== LDAP ===
 
As of CDash 1.4, authentication to an LDAP database can be performed.
 
This requires the ldap module for php. The variables to define:
 
 
 
  $CDASH_USE_LDAP='1'; // turn this to 1 for LDAP authentication
 
  $CDASH_LDAP_HOSTNAME='localhost'; // hostname of the LDAP server
 
  $CDASH_LDAP_BASEDN='ou=people,dc=organization,dc=com'; // Base DN
 
  $CDASH_LDAP_PROTOCOL_VERSION='3'; // LDAP protocol version
 
 
 
Note that the administrator (first user to install CDash) is always stored in the database.
 
 
 
=== Backup directory ===
 
The backup/log directory by default is placed in <tt>.../CDash/backup</tt>, this must be made writable by the account that you run Apache under (typically wwwrun or www-data), you can move the directory via:
 
 
 
// Backup directory
 
$CDASH_BACKUP_DIRECTORY = 'backup';
 
 
 
=== Removing registration ===
 
 
 
The registration can be disabled globally from CDash.
 
 
 
// Doesn't provide registration links
 
$CDASH_NO_REGISTRATION = '1';
 
 
 
=== Cookie expiration time ===
 
As of CDash 1.2 the login cookie time can be set in the config.php. The default is set to 1 hour.
 
 
 
// Duration of the cookie session (in seconds)
 
$CDASH_COOKIE_EXPIRATION_TIME = '3600'
 
 
 
This allows the browser to remember the login/password of the user.
 
'''On a public computer it is recommended to always log out'''
 
 
 
=== Google Maps ===
 
'''As of February of 2014, these links no longer work and I couldn't figure out where to point them.  A workaround is just to insert the empty string instead of a key.'''
 
 
 
CDash can use [http://code.google.com/apis/maps/ Google maps] to display the location of submission sites. CDash comes with Kitware's key code which won't work for your site's URL. Every site that uses Google maps requires its own [http://code.google.com/apis/maps/signup.html Google maps key] which you should obtain from Google (it's free), use this style URL when applying for a key:
 
 
 
http://mysite.org/CDash
 
 
 
Paste your newly obtained key in place of Kitware's:
 
 
 
$CDASH_GOOGLE_MAP_API_KEY['localhost'] = 'paste key here';
 
 
 
You may also add multiple keys (wighout the http://) and they will get matched by ''$_SERVER['HTTP_HOST']''
 
 
$CDASH_GOOGLE_MAP_API_KEY['www.vtk.org'] = 'paste key here';
 
  $CDASH_GOOGLE_MAP_API_KEY['www.cdash.org'] = 'paste another key here';
 
 
 
If your submission machines use private IP addresses you can add default location information, e.g. for all machines in the 192.x.x.x network (use http://maps.google.com to obtain your location):
 
 
 
$CDASH_DEFAULT_IP_LOCATIONS[] = array("IP" => "192.*","latitude" => "42.6612","longitude" => "-73.7689");
 
 
 
Sometimes site location are misreported (e.g. the ISP's location is used), you can override these:
 
 
 
$CDASH_DEFAULT_IP_LOCATIONS[] = array("IP" => "76.65.240.*","latitude" => "43.667","longitude" => "-79.417");
 
 
 
You'll probably want to replace the defaults that are present.
 
 
 
Note: If you use the 192.x.x.x address range ensure you update the location information before submitting from any machines in this subnet, as the location is stored in the database on first submission from a site (but can be subsequently edited from the admin web pages).
 
 
 
=== Google Analytics ===
 
CDash can use [http://www.google.com/analytics/ Google analytics] to monitor site usage. CDash's main <tt>index.php</tt> contains a reference to a default Kitware Google analytics code:
 
 
 
$CDASH_DEFAULT_GOOGLE_ANALYTICS='UA-701656-6';
 
 
 
When you configure each project you will have the opportunity to set a per-project Google analytics code.
 
See [[CDash:Administration#Adding_Google_Analytics | Adding GoogleAnalytics]] for more information.
 
 
 
== RSS directory ==
 
Ensure that the <tt>.../CDash/rss</tt> (and <tt>.../CDash/backup</tt>) directory is writable by the user account that Apache runs under (typically wwwrun).
 
 
 
== Apache ==
 
Ensure that the <tt>/srv/www/htdocs/CDash</tt> tree is accessible, you may have to add the following to your <tt>/etc/apache2/conf.d</tt> directory:
 
 
 
<tt>cdash.conf</tt>:
 
 
<Directory /srv/www/htdocs/CDash>
 
    Order allow,deny
 
    Allow from all
 
</Directory>
 
 
 
You may need to restart Apache:
 
 
 
  rcapache2 restart
 
 
 
or
 
  
service apache2 restart
+
== Configuring CDash ==
  
== Creating database ==
+
Create <code>CDash/config/config.local.php</code> and specify the following database settings.
Access your website to start the install process:
 
  
http://mywebsite.com/CDash
+
    // Hostname of the database server or name of unix socket
 +
    $CDASH_DB_HOST = 'localhost';
 +
    // Login for database access
 +
    $CDASH_DB_LOGIN = 'root';
 +
    // Port for the database (leave empty to use default)
 +
    $CDASH_DB_PORT = '';
 +
    // Password for database access
 +
    $CDASH_DB_PASS = '';
 +
    // Name of the database
 +
    $CDASH_DB_NAME = 'cdash';
 +
    // Database type
 +
    $CDASH_DB_TYPE = 'mysql';
 +
    // Must be one of host, unix_socket
 +
    $CDASH_DB_CONNECTION_TYPE = 'host';
  
The first step will confirm the host login and password for the database, the default admin account and password are also displayed, make a note of these as you'll need them later, as its easy to skip past this step missing them (you can always find them in <tt>.../CDash/sql/cdashdata.sql</tt>).
+
This allows CDash to connect to your database server.
  
== Production Mode ==
+
CDash can create a new database for you if you are using MySQL.  For Postgres, you have to create the new database yourself.
In order to disable the installation script, especially when the database is not accessible. You should turn on the option:
 
  
  $CDASH_PRODUCTION_MODE = true;
+
See [[CDash:Configuration]] for information about more configuration options.
  
in your config.local.php
+
== Installing CDash ==
  
== GIT support ==
+
Only CDash's <code>public</code> subdirectory should be exposed to the web. There are two main ways to accomplish this:
CDash 1.7 and higher are supporting GIT for daily update and also support the main GIT viewer (github, gittorious, etc...). In order to fetch the daily update, a bare (--bare) repository should be created for each project on the CDash server. Every night, CDash will fetch or clone the repository and parse the result of the 'git whatchanged' command. In order to allow git support.
 
  
* Create a 'git' directory and give the web server full write access to it
+
# Create a symbolic link from <code>DocumentRoot</code> to <code>CDash/public</code>.
* Edit your config.local.php and add these values corresponding to your system configuration
+
# Configure <code>DocumentRoot</code> to point directly to <code>CDash/public</code>.
  
  // Define the git command
+
See [[CDash:Upgrade#Repository_Reorganization_Aftermath|Repository Reorganization Aftermath]] for more details and information.
  $CDASH_GIT_COMMAND = 'git';
 
  // The default git directory where the bare repositories should be created
 
  $CDASH_DEFAULT_GIT_DIRECTORY = 'git';
 
  
 +
=== Permissions ===
  
== See Also ==
+
The web server user needs to have write access to the following directories:
[http://www.cdash.org/cdash/resources/software.html The CDash web site's brief install instructions]
+
* CDash/backup
 +
* CDash/log
 +
* CDash/public/rss
 +
* CDash/public/upload

Latest revision as of 10:36, 20 November 2018

< CDash Main Page

CDash is a LAMP application, running on Apache using PHP to access a MySQL or PostgreSQL database.

System Requirements

CDash requires:

  • A web server (Apache, NGINX, IIS) with PHP (5.5.9+) and SSL enabled.
  • Access to a MySQL (5.x+) or PostgreSQL (8.3+) database server.

PHP needs to have the following modules enabled:

  • bcmath
  • cURL (for site statistics)
  • GD (for regression tests)
  • mbstring
  • pdo-mysql or pdo-postgresql
  • XSL

Downloading CDash

Stable Release

The current stable release of CDash is 2.6.0 you can either download it as a zip archive

 git clone https://github.com/Kitware/CDash.git
 git checkout v2.6.0-prebuilt

Previous versions of CDash

GIT Development version

CDash uses composer and npm to manage its 3rd party dependencies.

We provide two developments branches, master and prebuilt. If you're working with the master branch, then you have to run composer & npm yourself. The prebuilt branch has these dependencies already downloaded for you.

master

Use the master branch if you'd like to modify CDash or contribute to its development.

git clone https://github.com/Kitware/CDash.git CDash
git checkout master
curl -sS https://getcomposer.org/installer | php 
php composer.phar install
npm install
node_modules/.bin/gulp

prebuilt

The prebuilt branch is a good choice if you'd like to use new features in CDash on a production server.

git clone https://github.com/Kitware/CDash.git CDash
git checkout prebuilt

Configuring CDash

Create CDash/config/config.local.php and specify the following database settings.

   // Hostname of the database server or name of unix socket
   $CDASH_DB_HOST = 'localhost';
   // Login for database access
   $CDASH_DB_LOGIN = 'root';
   // Port for the database (leave empty to use default)
   $CDASH_DB_PORT = ;
   // Password for database access
   $CDASH_DB_PASS = ;
   // Name of the database
   $CDASH_DB_NAME = 'cdash';
   // Database type
   $CDASH_DB_TYPE = 'mysql';
   // Must be one of host, unix_socket
   $CDASH_DB_CONNECTION_TYPE = 'host';

This allows CDash to connect to your database server.

CDash can create a new database for you if you are using MySQL. For Postgres, you have to create the new database yourself.

See CDash:Configuration for information about more configuration options.

Installing CDash

Only CDash's public subdirectory should be exposed to the web. There are two main ways to accomplish this:

  1. Create a symbolic link from DocumentRoot to CDash/public.
  2. Configure DocumentRoot to point directly to CDash/public.

See Repository Reorganization Aftermath for more details and information.

Permissions

The web server user needs to have write access to the following directories:

  • CDash/backup
  • CDash/log
  • CDash/public/rss
  • CDash/public/upload