The recommended method of installing LabTrove is to use the Ubuntu packages.
If you wish to install LabTrove on a system other than Ubuntu, or to install multiple instances, follow the instructions below.
Before you begin
First, ensure you have met the software pre-requisites.
There are two options for how to install a Trove:
- as a virtual host so that you have one DNS name per install
- onto a path as an alias.
The recommended option is to install the Trove as a virtual host. You might want to choose to install the on a path option if you plan to install multiple Troves on a single DNS name or as part of an existing website. See the instructions in Installing multiple LabTrove instances, for information on how to install your Trove as part of an existing website.
Installing the Trove as a virtual host
Complete the following steps to install the Trove as a virtual host:
Create a directory for the Trove in the location you want to install it. For example, if the directory to install the Trove is
/home/www/hosts/example.labtrove.org, then run the following command to create the new folder:
mkdir -p /home/www/hosts/example.labtrove.org
Take a copy of the LabTrove source, from the LabTrove website at http://www.labtrove.org/getlabtrove/
Change to the directory where the Trove is installed. For example, if you installed the Trove in the
/home/www/hosts/example.labtrove.org directory, run the command:
Configuring the MySQL Database
The next step is to configure the MySQL Database. Log in to the MySQL Server using the following command (where PASSWORD is the root password you created when you installed MySQL):
mysql --user=root --password=PASSWORD
To create a MySQL user called labtrove with a password labtrove and a database called labtrove, copy the following SQL code and paste at the mysql prompt:
CREATE USER 'labtrove'@'localhost' IDENTIFIED BY 'labtrove';
GRANT USAGE ON *.* TO 'labtrove'@'localhost' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0;
CREATE DATABASE `labtrove` ;
GRANT SELECT , INSERT , UPDATE , DELETE ON `labtrove`.* TO 'labtrove'@'localhost';
A script is provided to create the database tables need by LabTrove. Execute the following command (where PASSWORD is the root password you created when you installed MySQL):
cat install/sql/install.sql | mysql --user=root --password=PASSWORD labtrove
Setting up the configuration file
The next step is to set up the Trove configuration file. From the base of your LabTrove installation, run the following command:
cp install/config.php ./
Edit the new configuration file with the values appropriate for your instance. The configuration file contains comments explaining what the different values are for, but the key values are described below. Owing to the evolution of LabTrove Notebooks from a blog-based system, some internal variables do still use the term blog.
- The blog_title, blog_desc and blog_style variables are used to set the title description and style for the blog. To set a different style instead of the default style, see Configuring a Trove.
Trove server settings
- Set this_server to the IP or DNS name of the server that the Trove is to be hosted on.
- The blog_path usually stays as /, the root.
- Do not change the log_url.
- Set values for blog_webmaster to the username of the webmaster, and blog_contact to the username of the main contact for the Trove, usually the administrator.
Trove database settings
- Set the value for blog_host. If the database is on the same server as the Trove set this value to localhost.
- Set the value for blog_user. This should be the username of a MySQL account other than root.
- Set the value for blog_password. This is the password for the user database.
- Set the value for blog_db. This is the name of the Trove database.
Trove security settings
- Set the value for blog_zone. This is 0 for a public Trove or 1 for a private Trove.
- By default a Trove uses login_openid.
- If you want to allow new users to use the Trove, leave $ct_config['openid']['default_user_type'] at the default setting. Alternatively, if you want the administrator to authorise new accounts, change the setting to 0.
Trove terms of service
- If your site requires that users be made aware of Terms of Service (ToS) at each login, set the value for terms_of_service_link to the URL for your ToS page.
Setting up the .htaccess file
The contents of this file help the web server route page requests appropriately, The .htaccess file' must be (re)generated each time you change the Trove configuration file. To set up the .htaccess file, run the following commands:
Setting up the cache / upload folders
Before you can use the Trove, you need to change settings on the cache folder to change the owner, and make it writable. Run the following commands as root to make the changes:
chown -R www-data:www-data docs/cache uploads
chmod -R a+rwX docs/cache uploads
Adding the site to the Apache Web Server configuration
Use the following instructions to add the Trove site to the Apache Web Server configuration:
- Run the following command to open the Apache Web Server configuration file:
nano /etc/apache2/sites-available/example.labtrove.org, where example.labtrove.org is the location of your Trove.
- Add the following text to the configuration file, changing the appropriate values for your Trove:
<VirtualHost *:80> ServerAdmin webmaster@localhost DocumentRoot /home/www/hosts/example.labtrove.org/docs ServerName example.labtrove.org <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /home/www/hosts/example.labtrove.org> Options Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory> </VirtualHost>
Alternatively, if you want to deploy your Trove on HTTPS, add the following to the configuration file. (You may want to generate your own SSL certificate and key rather than using the snakeoil ones in this example):
<IfModule mod_ssl.c> <VirtualHost *:443> ServerAdmin webmaster@localhost DocumentRoot /home/www/hosts/example.labtrove.org/docs ServerName example.labtrove.org <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /home/www/hosts/example.labtrove.org> Options Indexes FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory> SSLEngine on SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key <FilesMatch "\.(cgi|shtml|phtml|php)$"> SSLOptions +StdEnvVars </FilesMatch> BrowserMatch "MSIE [2-6]" \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0 BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown </VirtualHost> </IfModule>
If you have chosen to setup your Trove to use HTTPS, if you have not already done so you will need to run the following two commands:
Finally, run the following commands to complete adding the site to the Apache Web Server configuration:
PHP configuration settings
In order to enable the Trove to accept files of up to 16MB in size you need to make some changes to the Apache Web Server's PHP Configuration settings:
- Run the following command:
- Change the following settings:
- post_max_size = 24M
- upload_max_filesize = 16M
Adding house keeping scripts
The final configuration set is to add some house keeping scripts for the Trove. Use the following instructions to update the crontab file:
- Run the following command to open the crontab file:
- Add the following lines to the crontab file, (substituting YOUR_USERNAME for your username on the server):
#House keeping scripts 47 * * * * www-data cd /home/www/hosts/example.labtrove.org/lib/scripts/ && php runscripts.php #Uncomment this if you want to enable auto update, and select a random time so not hit our servers at the same time #49 3 * * * YOUR_USERNAME cd /home/www/hosts/example.labtrove.org/install; php update.php auto
What to do next
- Installing multiple LabTrove instances
- Applying patches to a LabTrove instance
- Configuring a LabTrove Instance
- Administering LabTrove
- Troubleshooting a LabTrove instance