__TOC__

Installation

Prerequisites

• A Java 1.6 servlet 2.5 and onwards container. Tested on Apache Tomcat 7 and 8, Oracle Glassfish 3, Jetty 7, 8, and 9, with Sun JRE 6, Oracle JRockit and OpenJDK 7.
  • If you use Glassfish, Comet support must be explicitly enabled within the servlet container configuration.
  • If you use Glassfish 4, you might have to workaround some discrepancies between CDI 1.0 and 1.1: remove the packaged library named bonecp-0.8.0.RELEASE-with-guava-17.0.jar and replace it with both BoneCP and the latest Google Guava libraries that you can download by yourself.
  • If you have a Servlet 3.0-compliant container, and wish to benefit from its improved capabilities, follow the comments within the file /WEB-INF/web.xml and upgrade it accordingly.
• A supported DBMS (database engine) and preferably one that understands relational integrity. Tested on MySQL 5, MariaDB 5, Apache Derby 10.6 and 10.8 in network-mode, and PostgreSQL 8.4. The embedded [www.h2database.com/ H2] engine is only for testing purposes as you cannot edit or backup data from the database using external tools when Shampoo is running.
• Liquidsoap 1.1.1 commit 8afa479 (May 22, 2014), or later. See this page for more details. Older revisions of Liquidsoap are only compatible with legacy versions of Shampoo but are not supported anymore.

The above softwares are not provided with Shampoo and must be downloaded and installed separately.

Although it's recommended if it's your first time installing Shampoo, you are absolutely not required to host everything on the same server. You can relocate all of these softwares on distant machines in your network.

Database creation

Shampoo needs to store its data in a database. You must first create a database for Shampoo to use, the application must have full table-level CRUD (create, read, update, delete tables and rows) rights over the database for unlocking all its functionalities. Please refer to the documentation of your RDBMS. See in the next section how to update the main Shampoo configuration file with the database connection credentials you've just defined.

Once the database has been created, it must then be initialized. There are two ways to first initialize the database Shampoo will use:

• You can either use the provided initialize_database command-line tool
• Or manually fill in the database structure.

CLI tool

You must first properly configure your database connection with Shampoo. See the next section.

1. Open a Shell command line prompt and change directory to the /Shampoo folder from either the compressed or the the decompressed distribution archive. cd Shampoo

2. run the initialize_database script without any parameters. You are not required to launch the script with the same user as your Servlet container. Windows users can type: WEB-INF\scripts\initialize_database

   and Unix/Linux users:

   sh ./WEB-INF/scripts/initialize_database.sh
   

If your servlet container is a full Java application server which includes the JDBC driver for your database, you must first copy the relevant JDBC JAR driver within the lib folder for the script to work. If you use the embedded H2 engine, be sure to shutdown any running servlet container accessing the database first.

When you upgrade your installation to a minor version of Shampoo, you can use the update_database script located within the same folder and update the database structure to any new changes. However, you should manually audit and update your database schema when you switch to any major revision of Shampoo. Use the SQL schemas provided with the distribution archives. As usual, you are not required to execute the script with the same user as your Servlet container. Shampoo must be shut down before using this script if you use the embedded H2 engine.

Manual creation

Please note that the database structure may evolve until the 1.0 milestone is reached. The full database SQL schema, written in a few major RDBMS dialects, is available in the root folder of the installation archive you've downloaded. An example script file for MySQL 5 is available here.

1. Adapt, if needed, and import the SQL script that fits your RDBMS engine to create the new database schema. Try to stick to the UTF8 charset if possible, proper internationalization support depends on it. Please refer to your RDBMS vendor documentation for further info.

   • Always use one of the scripts bundled with the installation archive when updating, the database structure may be slightly altered between different revisions.
   • Please note that no indexes are included in those scripts. Adding indexes to columns should be a carefully-crafted manual process, only depending on the amount of stress your database will have to handle. Ask your DBA for help.

2. Add a default Administrator user to the database; this account will allow you to perform everything from the web frontend from now on. INSERT INTO people (login, type, version, creation, creator, latestmodification, latesteditor, realname, password, email, enabled, timezone, email_notification) VALUE ('admin', 'administrator', 0, '2010-10-08 14:11:45', NULL, NULL, NULL, 'The Boss', 'password', 'admin@localhost', TRUE, 'UTC', TRUE);

   The login for the new account is 'admin', and the password is 'password', simple.

Install the database driver

For Shampoo to communicate with your database, you must install an appropriate driver. Skip this step if you wish to use the default embedded H2 engine.

1. Download the JDBC driver that matches your RDBMS engine. A list can be found here. You can also visit the website of your RDBMS vendor and download it from there.
2. Copy the required JAR file(s) into the /WEB-INF/lib/ folder of the application. Consult the JDBC driver documentation if you're not sure which files must be installed.
3. Remember the full name of your JDBC driver, it is mandatory for configuring Shampoo, as noted below. Once again, refer to your specific JDBC driver documentation if you don't know the full name.
   • For example, if you use Apache Derby as a database, your JDBC driver is derbyclient.jar and its full name is org.apache.derby.jdbc.ClientDriver. Download the latest driver here.
   • For MySQL 5.1 with InnoDB and MariaDB, the driver is mysql-connector-java-5.1.17-bin.jar (or later) with the full name com.mysql.jdbc.Driver. It can be downloaded here.
   • For PostgreSQL 9, the JDBC driver is postgresql-9.1-901.jdbc4.jar (or later) with the full name org.postgresql.Driver.

Configuring Shampoo

See the dedicated page for complete instructions

Configuring Liquidsoap

See the dedicated page for complete instructions

Deploying Shampoo

After properly configuring Shampoo, the application is ready to be deployed within your servlet container and will start performing its tasks.

Please refer to your servlet container or application server documentation for configuring the application Context Path (make it match your *.deployment.url settings) and other miscellaneous options you might require, such as the maximum upload size limit for example.

You can also fine tune how Shampoo behave by editing the various XML configuration files located in the /WEB-INF and /META-INF folders. E.g. log activities are controlled through the file /WEB-INF/conf/log.properties file, and how data is cached on disk and in memory via the files /WEB-INF/classes/ehcacheXX.xml. Their usage is not covered in this document.

Depending on which different modules you use and whether they're remotely or locally accessible, you might have to adjust your network topology and configuration. You will also likely want to start your servlet container as soon as your server is up and running, a simple and manually designed System V or upstart script for such a task is sound. Some servlet containers can even provide that feature for you. Just be sure that deployed applications are automatically started as soon as the servlet container is launched. Here's an example NetBSD rc.d script for Jetty and a Debian 'default' configuration file, still for Jetty.

Shampoo won't automatically start your database when it's booting, nor your streaming software, so please refer to their relative documentation to make them start on boot as well. For Liquidsoap please refer to that page. The database must be already running when Shampoo starts, it doesn't matter for the streaming software. Your datastore implementation might also require that an FTP or HTTP server runs in the background, consult the documentation provided with your datastore in this case. The default localFilesystem datastore needs no external daemons to work, unless the files are remote and served through CIS or NFS for example.

• If different modules of Shampoo are meant to be locally distributed through your network, you are strongly advised to synchronize all your clocks. This is especially true for your streaming software to correctly communicate with Shampoo private webservices. For Unix machines, the use of NTP synchronization methods is recommended.

Importing existing data from a legacy system

See the dedicated page for complete instructions