Advanced manual setup

Advanced manual setup

Altough you can use MateCat in the virtual machine appliance with only a little performance overhead, high load environments administrators may wish to deploy MateCat on “bare iron”.

If you have already installed Matecat v0.5.7 on your machine, please follow the guide to upgrade to version 0.5.9

MateCat requires Apache, MySQL, PHP, ActiveMQ, Redis and Node.js, and runs on Linux.

Windows and Mac

Running MateCat natively on Mac or Windows is not supported.
If you want to install MateCat on Windows or Mac we suggest using the virtual machine appliance provided.
This guide will focus solely on Linux setup.


This guide will assume you are on a Debian based Linux distribution (Debian >= 6 or Ubuntu >= 12.04).

Below are listed the mandatory dependencies for MateCat. If your server already meets these requirements, please jump straight to Configuring components section. Otherwise the section that follows, Configuring the environment from scratch, will guide you to a ready to work environment.

Mandatory dependencies are

  • Apache2 Web Server >=2.2.x, with following modules enabled:
    • htaccess
    • rewrite
    • filter
    • deflate
    • headers
    • mod_version
    • proxy_http.load
  • PHP >=5.2, with following extensions enabled:
    • php5-mysql
    • libapache2-mod-php5
    • php5-curl
    • php5-json
  • MySQL >=5.1
  • git >1.5
  • screen utility
  • ActiveMQ >=5.11
  • Redis >=3
  • Node.js

Go to top

Configuring the environment from scratch

The setup requires root access privileges.

If you are running on Ubuntu, get root privileges with:

sudo su

If you are running on Debian, issue:


and update your repositories:

apt-get update

Install Apache

apt-get install apache2

Go to top

Enable Additional Modules for Apache

Apache web server needs to be fine tuned for MateCat to work properly. Enter these commands to enable required Apache submodules

a2enmod rewrite filter deflate headers expires mod_version proxy_http.load
apache2ctl restart

Last command is mandatory for changes to take effect. If you see, upon issuing apache2ctl restart, the following warning:

Could not reliably determine the server’s fully qualified domain name, using for ServerName

do not worry, it’s not important.
Go to top

Install MySQL

apt-get install mysql-server mysql-client

The installation process will prompt a few times for a new password. Please ensure you type the same every time. You can test the reachability of the database by issuing at a terminal:

mysql -u root -p

If you specified a password during MySQL setup, type it when prompted; otherwise, just hit Return. If everything went fine, you should see the greeting message and the shell prompt:


Finally issue the following command to quit:


Go to top

Install PHP5 core and additional packages

apt-get install php5 php5-mysql libapache2-mod-php5 php5-curl php5-json

Go to top

Install screen utility

apt-get install screen

Go to top

Install Active MQ

ActiveMQ requires an installed version of Java. If you don’t have java installed just type:

apt-get install openjdk-7-jre

The latest ActiveMQ 5.11 release is now 5.11.3. In the next steps we will assume that as the downloaded version. For downloading it:


Extract the tarball

tar xzf apache-activemq-5.11.3-bin.tar.gz

Move it to the /opt folder

mv apache-activemq-5.11.3 /opt

Create a soft link to the folder for ease of next steps

ln -sf /opt/apache-activemq-5.11.3/ /opt/activemq

Create an “activemq” user and allow it to execute bash scripts

adduser -system activemq
sed -i 's#activemq:/bin/false#activemq:/bin/bash#g' /etc/passwd

Change ownership of activemq folders

chown -R activemq: /opt/apache-activemq-5.11.3/

Sym-link the init script provided by Active MQ to /etc/init.d/activemq

ln -sf /opt/activemq/bin/activemq /etc/init.d/

Set the init script to be executed on boot

sed -i 's#exit 0##g' /etc/rc.local
sh -c 'echo "/bin/sh /usr/bin/activemq start" >> /etc/rc.local'

Create a default configuration file with ActiveMQ, change ownership and group for this file and make it accessible only by root

/etc/init.d/activemq create /etc/default/activemq
chown root:nogroup /etc/default/activemq
chmod 600 /etc/default/activemq

Enable ActiveMQ connector for the web interface

sed -i 's/Context createConnector='false'/Context createConnector='true'/g' /etc/default/activemq/conf/activemq.xml

Sym-link ActiveMQ into /bin/bash so that it can be easily called into terminal

ln -s /etc/init.d/activemq /usr/bin/activemq

Done! You can now start ActiveMQ by typing

activemq start

Optionally, ActiveMQ tar.gz file downloaded at the beginning is not necessary, and can be removed:

rm apache-activemq-5.11.3-bin.tar.gz

Go to top

Install Redis

Differently from ActiveMQ, Redis will automatically start on boot.

apt-get install redis-server

Make redis listen on all ports

sed -i 's/bind' /etc/redis/redis.conf

Done! You can launch it by typing

service redis-server restart

Go to top

Install Node.js

Node.js is necessary to have a realtime chat within matecat. Install it and its Package Manager with:

curl -sL | sudo -E bash -
apt-get install -y nodejs

And use the Node.js package manager to install Grunt

npm install grunt
npm install -g grunt-cli

Finally make sure Node.js will start at startup

echo "screen -d -m -S 'node' node \/home\/matecat\/cattool\/nodejs\/server.js" >> /etc/rc.local

Go to top

Important notice for ActiveMQ and Redis (optional)

ActiveMQ provides a Web Console binded on port 61613.
This means that if your machine is accessible externally, then everyone can access the web console.
In the same way, Redis accepts command-line connections on port 6379.
Remember to add the proper firewall rules to prevent unauthorized access.
Go to top

Configuring components

Tune PHP configuration

Edit PHP configuration file for the command line configuration:

echo "short_open_tag = On" >> /etc/php5/cli/php.ini
echo "memory_limit = 1024M" >> /etc/php5/cli/php.ini

As usual, restart Apache for changes to take effect:

apache2ctl restart

Go to top

Installing MateCat

This section assumes you’ll install MateCat under the home of user matecat (/home/matecat).
In order to create that user, use the following:

adduser --disabled-password --gecos "" matecat

Install git and clone the  repository

If you already have GIT, skip this section. Otherwise, install GIT by typing:

apt-get install git

Switch to the newly created user

su - matecat

Then clone the repository in /home/matecat:

git clone cattool

The above will create the directory cattool and will download all MateCat codebase in it. Go to top

Initialize the database

Navigate to the configuration directory:

cd ~/cattool/lib/Model

and send the database template to your MySQL instance with the following command

mysql -u root -p < matecat.sql

Type the MySQL root password when prompted

Important notice for remote MySQL setups (optional)

Please note that the grants for the default database user (matecat) are open to any host: matecat@%.
In case you are deploying the database on a public server we suggest to limit the hosts with access privileges.

Use the commands below to limit access to localhost only, or replace “localhost” with the IP of the server MateCat is running on:

Open a MySQL shell (type the password when prompted)

mysql -u root -p

Delete the current “matecat” user

delete from mysql.user where user = 'matecat' and host = '%';

Create a new matecat user with access privileges limited to only some hosts

grant all privileges on matecat.* to 'matecat'@'localhost' identified by 'matecat01';

Quit from mysql shell


Go to top

Create the virtualhost

Navigate to the directory

cd ~/cattool/INSTALL

Create the virtualhost file from the sample template

cp matecat-vhost.conf.sample matecat-vhost.conf

and use the following command for replacing the string @@@path@@@ in the virtualhost with the fullpath of the cattool folder previously created via the clone action (in this guide it’s assumed to be /home/matecat/cattool):

sed -i "s/@@@path@@@/\/home\/matecat\/cattool/g" matecat-vhost.conf

IMPORTANT NOTE: In the virtualhost file are specified the maximum values for memory, upload and post size.
By default these values are:

  • memory_limit: 1024M
  • upload_max_filesize: 200M
  • post_max_size: 200M

If you need to change these values, open the virtualhost in an editor:

nano matecat-vhost.conf

And customize the default settings. Finally, save and close the editor.

Go to top

Install the virtualhost

Enable the web application in Apache with the following commands:

mv /home/matecat/cattool/INSTALL/matecat-vhost.conf /etc/apache2/sites-available
a2ensite matecat-vhost.conf
apache2ctl restart

Go to top

Create and customize MateCat configuration

Go to your matecat root folder in order to install PHP composer packages

php -r "readfile('');" | php
php composer.phar --no-dev install

We are nearly there! Go to configuration subdir and create your config file from sample template:

su - matecat
cd ~/cattool/inc
cp config.ini.sample config.ini
cp task_manager_config.ini.sample task_manager_config.ini
sed -i "s/\/home\/matecat\/storage/\/home\/matecat\/cattool\/storage/g" config.ini

This configuration works out of the box, with very default settings. Have a look at next sections to further refine basic parameters Go to top

Compile Javascript code

Move to the Grunt configuration folder:

cd ~/cattool/support_scripts/grunt

Prepare the environment and deploy the source code

npm install
grunt deploy

Go to top

Configure Node.js

Move to the Node.js configuration folder:

cd ~/cattool/nodejs

Create the configuration file, out of the sample one

cp config.ini.sample config.ini

And prepare the environment

npm install

This configuration works out of the box, with very default settings. Please edit the config.ini file you just created to customize your settings

Go to top

Configure database address (optional)

If your database resides on another machine, open the config.ini file, and in [production] section change the directive:

DB_SERVER = 'localhost';


DB_SERVER = '<your_db_server_uri>';

And update the DB_USER and DB_PASS accordingly

Go to top

Turning on the analysis daemon

Volume analysis is a MateCat feature that counts full or partial repetitions in the file and searches for translation memory matches. To enable the analysis:

Enter daemons directory

cd ~/cattool/daemons

Configure the number of workers (each worker takes 13M of memory, on average)

echo '25' > .num_processes

Start fast Analysis and TM Analysis daemons:

/bin/bash /home/matecat/cattool/daemons/

If you see a message stating “Spawning daemons” it means they are running

Remember to configure your server for the automatic startup of this script on each boot.

sh -c 'echo "/bin/sh /home/matecat/cattool/daemons/" >> /etc/rc.local'
sh -c 'echo "exit 0" >> /etc/rc.local'

Finally ensure apache has write permission in storage directory

chown -R www-data /home/matecat/cattool/storage/

Go to top

Turning on Node.js

Run Node.js server in a screen with the following command:

screen -d -m -S 'node' node /home/matecat/cattool/nodejs/server.js

Go to top

Enabling Google+ login

Warning: this feature is optional, but without it MateCat can only be used in anonymous mode

MateCat uses Google+ login as authentication mechanism: you can keep track of your projects in a private panel under “Manage” section by logging in with any valid Google account. Note that this is not limited to GMail: any valid email address can be used, upon registration as a Google account.

In order to enable it, you need a Google account
If you don’t have a client id and client secret, please visit Google Developers Console and follow these instructions:

  1. click on “Create Project“, specify a project name, a project ID and check “I agree with Google ToS” checkbox; it may take a little to create your project
  2. click on your newly created project
  3. select “APIs & auth” on left sidebar
  4. scroll down the list to “Google+ API” and switch the status of ON
  5. go back to left sidebar and, under “APIs & auth” menu, select “Credentials
  6. click on “Create new client ID” buttonu
  7. under APPLICATION TYPE, select “Web application” option
  8. under AUTHORIZED JAVASCRIPT ORIGINS, insert the domain MateCat will be accessed from
  9. under REDIRECT URIs, insert “http://<domain>/oauth/response” or “http://localhost/oauth/response”, where <domain> is the domain that you specified in the previous step
  10. click on “Create client ID“. Take note of the “Client ID” and a “Client secret” you just obtained
  11. go back to left sidebar and, under “APIs & auth” menu, select “Consent screen
  12. under PRODUCT NAME, choose a meaningful name (for example, MateCat)
  13. scroll down the page and click “Save
  14. Finally, edit the file ~/cattool/inc/oauth_config.ini.sample, replacing the default parameters with those obtained in the previous step:
    1. OAUTH_CLIENT_ID with your client ID
    2. OAUTH_CLIENT_SECRET with your client secret
    3. OAUTH_CLIENT_APP_NAME with your custom app name,or leave MateCat
  15. save the file as oauth_config.ini
  16. change permissions for the ini file with:
    chmod 400  ~/cattool/inc/oauth_config.ini
    chown www-data:www-data ~/cattool/inc/oauth_config.ini

    so that only apache has read access.

Go to top

Translating other formats than XLIFF (optional)

MateCat directly supports XLIFF files only, but using an additional component it can support almost any file format. The additional component you need is MateCat Filters.

The easiest way to enable MateCat Filters is using our hosted API on Mashape. It’s very simple:

  1. Go to the Filters page on Mashape and choose your plan. You can begin using the Basic plan, with 250 free API calls per month.
  2. Click the subscribe button of your preferred plan and complete the subscription process.
  3. When successfully subscribed, use the Applications menu on top of the page and click on the application you are using (for new accounts it’s “Default Application”).
  4. In the application page click on the “Get the keys” button on the right, near the top, then copy your key.
  5. Back to your MateCat install folder, open inc/config.ini, look for the FILTERS_MASHAPE_KEY parameter in the [production] section, and paste your key:
    DB_SERVER = "localhost"
    DB_DATABASE = "matecat"
    ; ...
    ; Filters Configuration
    FILTERS_MASHAPE_KEY = B3uowdUhVFmshBNV5VVYPUpSccx7p1PcSsrjsnT7f54ozqiCgz

Simple, isn’t it? Just add a working FILTERS_MASHAPE_KEY and you are done. You can then load any file you want in MateCat.

The steps above are the easiest way to attach Filters to MateCat, but if you want you can attach your personal instance of Filters too.

MateCat Filters has its own open-source repository. Read the wiki in the repo to learn how to build your local instance.
To make MateCat talk with your Filters instance simply edit the FILTERS_ADDRESS parameter in inc/config.ini, for example:

FILTERS_ADDRESS = http://localhost:8732

In this case you can ignore the FILTERS_MASHAPE_KEY parameter, it has no effect for instances running outside of Mashape.

Pay attention that MateCat Filters relies on some commercial components to support certain filetypes (PDF and OCR, for example).
If you run a local instance of MateCat Filters you’ll have to buy and install the required commercial components to support all the file formats.
Using the hosted version available on Mashape you don’t have to bother about this.

For all the info on MateCat Filters and a full list of the hosted API features see

Update MateCat

If you have already installed your MateCat instance, follow this guide to keep your instance up to date.

That’s all. Now type http://localhost in Chrome or Safari and enjoy your fresh install.

If you need further assistance, please contact support [a t] matecat . com

Go to top