Installation and Configuration
Installing CatDV Server
Once you have installed the necessary prerequisites and ensured that your Database Server is correctly configured and running you are ready to install the CatDV Server software.
Mac OS X (including Mac OS X Server)
1. Double click on CatDV Installer.mpkg and follow the instructions, entering your administrator password when prompted.
2. After the installer has completed it will launch the CatDV Server Control Panel to allow you perform the post-installation configuration tasks including entering your license details. See sections 3.5, 3.6 and 3.7 for further details on entering your registration code and starting the server.
Windows
1. Double click the CatDVServerX.X.X.exe setup file and follow the instructions. It is recommended that you accept all the defaults suggested by the installer.
2. You may be asked to confirm that you want to allow Install CatDV Server to make changes to your system. You must click Yes at this point to allow the installer to proceed.
3. After the installer has completed it will launch the CatDV Server Control Panel to allow you perform the post-installation configuration tasks including entering your license details.
Generic Unix/Linux
1. The Linux distribution of CatDV Server is supplied as a simple ZIP archive. Download this into a temporary location and expand the ZIP file.
2. In the root of the expanded archive you will see a catdvServer folder that contains the software and an install.sh installation shell script.
3. Run the install.bat script with administrator privileges:
./install.sh
4. This will copy the installation files to /usr/local/catdvServer and also create an entry in /etc/rc.d/init.d to launch CatDV Server as server start up.
5. The last step in the install script is to launch the CatDV Server control panel. This will present you with the CatDV Server Setup Wizard that will lead your through the post-installation configuration tasks.
Post-Install Setup
Once the installation process has completed the installer launches the post-installation Setup Wizard, which will lead you through the steps required to set up CatDV Server for first use. The Setup Wizard is actually part of the CatDV Server Control Panel application and can be accessed at any time from the Control Panel if for any reason you need to make changes to the configuration.
The Setup Wizard
The Setup Wizard consists of a number of steps – each one on a separate tab. Normally you will fill in the information required on each tab and then press Next > to move onto the next one. You can however go directly to a particular step by clicking on the desired tab.
Each tab has a small icon on it that indicates the status of that section. A green tick indicates all information has been filled in and verified, a yellow warning triangle indicates the current settings are valid but you should check the warning message on the tab, and a red cross indicates missing or invalid settings.
Installation
In normal use the wizard will skip this step as it should never need changing.
It allows you to manually specify the install location of the server and the MySQL Dump application.
Licensing
In normal use the wizard will display the Licensing step first, which allows you to enter you license details.
The operation of the server, including how many client connections are permitted, is controlled by a license key or registration code. You will have been sent an email that will contain some lines of text such as the following example.
reg.user = Trial
reg.code = OGOP-JZXL-G1TD-65SI-7F7B-YZ3X-GVJD-6YQQ
(Please contact [email protected] if you do not have your registration code.)
To enter you license code into the control panel you can copy the whole text of the email and then click the Paste buttons next to the Server and Web license fields. The control panel will automatically scan the email text and extract the relevant fields for you. You can also, of course, enter the values manually. You may have two separate license codes, one for the CatDV Server and one for the Web Client.
Once you entered the license details the red cross at the top of the page should change to a green tick. You can now click Next >. Database
The next screen lets you configure CatDV Server’s database connection. It is assumed that, if you wish to use an external database server, such as MySQL or Microsoft SQL Server, that the database server itself is already installed and configured as described previously.
You should first select the database Server Type. This can be:
CatDV Server built-in database – starting with version 6.8 CatDV Server has a database built into it, so it is no longer necessary to use an external database server. This is the default selection and it is ideal for smaller installations.
MySQL or Microsoft SQL Server – are popular third party database servers. If you select one of these you will need to purchase and install it separately and set it up as described previously. These database servers can provide enhanced performance and robustness for larger installations.
Once you have selected the type of database you will be using, the wizard will fill in default values for the other fields (Port, Username/Password and Database). In most cases, if you have selected the recommended settings during set up, then these will be the correct values, but for Microsoft SQL Server you will commonly need to change the username and password.
You can at this point click the Next > button, which will attempt to set up the database using the supplied information. You may be asked for permission to install the CatDV Server schema – you need to accept this to continue. Alternatively you can click the Apply button to manually verify the credentials and other settings you have entered. This will connect to the database and query it for any pre-existing schema and then display the results in the Installed Schema field. You can then choose to manually Install Database or Update Database as appropriate.
Web Server
Starting with version 6.8, CatDV Server provides a built-in web server (based on embedded Tomcat) that can be used as an alternative to installing a separate copy of Tomcat. For new installations it is recommended that this new built-in web server is used, but for existing installations that already use Tomcat you may choose to continue to use Tomcat.
The updated Web Server tab of the Control Panel provides a choice of three options for the web server you want to use:
Built-in – the built-in web server recommended for new installations
Tomcat (Deprecated) – for existing installation that do not wish to migrate to the built-in server at this point
None – for installations that aren’t using the web interface or where Tomcat is to be manually installed on a separate server.
Built-in Web Server Configuration
If you select the built-in web server the following configuration options will be available:
This step has the following fields:
Port – the TCP Port that the embedded we server should listen on. Also the port that the control uses to monitor the status of the web server. Document Root – Location of the root directory (or Java war file) containing the web files that will be published by the embedded web server. Initially this is set to the location of the sample web applications included with the installation. If you wish to create your own customised web interface based on one of these samples you should copy them to another location and then update this field to point to that, otherwise the site will be overwritten next time you update the CatDV Server software.
Note: the CatDV Web Client application itself is not served from this location – it is built-in to the server and is configured to appear at /catdv2. So – if your server is called my_server and the port is set to the default of 8080 then http://my_server:8080 will display the web site stored at document root and http://my_server:8080/catdv2 will display the CatDV Web Client.
Working Directory – a directory where the embedded web server will store it’s working files, such as caches. This probably won’t need to be changed.
Migrating from Tomcat to the Built-in Web Server
If you are currently using Tomcat to host the CatDV Web Client, but you wish to switch over to using the built-in web server, you must uninstall Tomcat (or at least shut down and disable it). Failure to do this will prevent the built-in web server from starting. In the CatDV Server Control Panel Set up Wizard you may see an error message: “Port 8080 in use”. This is symptomatic of Tomcat still running on your machine.
Tomcat Configuration (Deprecated)
If you are still using a separate Tomcat instance on the same server (which is not recommended) the following configuration options will be available:
This step has the following fields:
Port – the TCP Port that Tomcat is configured to use. This is the port that the control uses to monitor the status of the web server.
Install Path – Location of the the Tomcat installation directory. This is normally filled in automatically and should not need to be changed. Service Name (Windows Only) – the name of the Windows Service that Tomcat runs as. Used to stop and start Tomcat. Usually filled in automatically.
Installation of the Web Client under Tomcat requires that the a file – “catdv2.war” – is copied into the Tomcat webapps folder. The Install/Update Web Client button performs this action. The wizard will also do this automatically when you click Next if required. You can also Start/Restart Tomcat from here if required.
Click Apply to verify the settings, or Next > to move to the next step.
CatDV Server
The final step lets you configure CatDV Server’s network settings.
This step has the following fields:
Server host – the publicly visible hostname or IP address of this server – that is the hostname or IP address that CatDV desktop clients will use to connect to the server. You may need to consult your network administrator for the correct value.
Server port – the TCP Port number that the server should listen to to server Java RMI requests from the desktop clients. This should not normally need to be changed.
On first run the control panel will attempt to fill in default values to the local address and the ports.
Click Apply to verify these settings, then press Finish. You will be prompted to start the CatDV Server if it is not already running, or to restart it if you made any changes.
Troubleshooting
MySQL Issues
If mysql_install_db gives an error about hostname use the –force option.
If you get errors when starting the MySQL server, look at the .err files in the data directory for details.
Note that “root” means the mysql administrator, ie. the name of a database user as understood by MySQL, not the Unix root login user as understood by the operating system. On the other hand “mysql” does refer to a login user account. This can be somewhat confusing, so pay careful attention to the context so you know what is being referred to.
If you get an SQL error “Server configuration denies access to data source” the most likely reason is a DNS issue and your machine is not ‘localhost’. Make a note of the hostname after the ‘@’ then type the following (inserting the actual hostname as appropriate):
mysql -u root -psecret (where secret is the MySQL root password) GRANT ALL PRIVILEGES ON catdv.* to catdv@hostname ;
GRANT RELOAD,SHUTDOWN on *.* TO catdv@hostname; FLUSH PRIVILEGES;
Press Ctrl-C to come out of MySQL and run ./launchServer again.
If you run the CatDV Server and/or Web Interface on a different machine from the MySQL database you will need to change the database URL to refer to the machine on which the MySQL server is running and within MySQL you will need to grant access to the other machine(s) using a GRANTstatement as above. Additionally, you may need to open up access to the standard MySQL port 3306 in your firewall. If you are unable to determine which hostname to use, then, as a last resort for testing purposes, you could try:
GRANT ALL PRIVILEGES ON catdv.* to catdv@"%" ; FLUSH PRIVILEGES ;
but beware, this leaves a gaping hole in your database security and once you have identified the issue you should fix the problem.
Mac OS X-specific issues
Under Mac OS X 10.2 and later, /usr/local/bin/ is no longer in your path and you will need to explicitly type /usr/local/mysql/bin/mysql instead of just mysql. You also need to download the special Jaguar release of MySQL..
With Mac OS X 10.3 and later you no longer need to create a mysql user. If you are using an older version of Mac OS X and don’t have a mysql user you can create one using the Users pane of System Preferences. You may also want t consult http://developer.apple.com/internet/macosx/osdb.html.
If the CatDV Mac Installer reports a failed installation, do File > Show Log, then select “Show Everything”. The most common cause of errors is that MySQL is not installed or is not running.
If you are using Mac OS X 10.5 and start MySQL using the CatDV control panel then MySQL will inherit your own personal tmpdir temporary directory which it doesn’t have access to. This can cause the CatDV client to fail with error messages such as “prepareQuery failed (Can’t create table ‘tmpclips’) (errno:13))” when you try to perform a query. To resolve this, make sure you have a my.cnf config file which explicitly specifies a tmpdir to use (see 3.2 above).
Windows firewall settings
If you can connect to the server with a client running on the same machine but not from another machine on your network then access to the server is probably being blocked by the Windows Firewall software.
Open the Windows Firewall settings (Start menu > Control Panel > Security Settings > Manage security settings for Windows Firewall). It is recommended that you leave the firewall settings ON, but permit access to the CatDV server using the Exceptions tab:
1. Click on Add Program… then browse to the directory where you installed the CatDV server (eg. C:Program FilesSquare BoxCatDV Server 5.0) and select JSHelper.exe
2. Click on Add Port… and enter “Java RMI” for the Name, “1099” for the port number, and check the TCP button.
Other Windows-specific issues
When installing on Windows 2000 the installer may fail saying command REG not found. This is because you may not have a copy of the registry editor REG.EXE in your path. If so, you may need to copy REG.EXE from another machine (contact [email protected] if you need further assistance).
Check the CatDVServer logs in C:\TEMP if the server fails to start
Try launching the CatDV Server manually from the NT Services control panel. If it fails there the message may display additional useful information. Check the properties of the service to make sure things like the directory it’s running from are what you expect.
CatDV Server troubleshooting
Launch the CatDV Server Control Panel and press the Details and View Log buttons to display diagnostic information.
If the server does not start automatically using the NT service or OS X startup item, try launching it manually from the command line as this may make it easier to see any error messages that are displayed.
For testing purposes you may find it convenient to install the CatDV Pro client application on the server machine. It is not necessary to do so however, and you do not need to install QuickTime on the server machine for the Workgroup Server software to function.
The most likely cause of the server not starting is that you haven’t inserted a valid registration cause into the catdv.properties file.
Other common causes are that the MySQL database isn’t running, that you didn’t create a catdv database, or that the RMI port 1099 is already in use by another application (in which case pick a different port in the catdv.properties file).
If you can connect to the server with a client running on the same machine but not from another machine then one possible explanation is a firewall issue. Another, more insidious, possibility relates to the way Java RMI works. When you enter the IP address of the server in the Connect To Server dialog on the client you are actually specifying the location of a naming registry which returns the actual CatDV server location. In order for this to work, the server needs to be told its own IP address as used by clients when connecting to it. In certain situations (such as if the server has multiple network adapters) the naming service may not correctly identify its own IP address, so clients will be unable to connect properly. To resolve this issue, use the CatDV Control Panel to edit the Server Config and enter the server’s own IP address under Host & Port. (If you edit the catdv.properties file then you need to set java.rmi.server.hostname.)
Log files
A log file called server.log is often written in the server directory. This contains diagnostic information. You can also view this log file from the CatDV Control Panel.
Under Windows, you may find C:\Temp\CatDVServer.stdout.log and C:\Temp\CatDVServer.stderr.log files that also contain useful information. Under Mac OS X the console.log and system.log files, accessible via the Application > Utilities > Console application, may also contain useful diagnostic information.