Advanced manual setup
- Windows and Mac
- Configuring the environment from scratch
- Configuring components
- Installing Matecat
- Install git and clone the repository
- Initialize the database
- Create the virtualhost
- Install the virtualhost
- Create and customize Matecat configuration
- Configure Node.js
- Turning on the analysis daemon
- Turning on Node.js
- Enabling Google+ login (optional)
- Translating other formats than XLIFF (optional)
- Update Matecat
Although 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.
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:
- PHP >=5.2, with following extensions enabled:
- MySQL >=5.1
- git >1.5
- screen utility
- ActiveMQ >=5.11
- Redis >=3
The setup requires root access privileges.
If you are running on Ubuntu, get root privileges with:
If you are running on Debian, issue:
and update your repositories:
apt-get install apache2
Apache web server needs to be fine-tuned for Matecat to work properly. Enter these commands to enable the required Apache submodules
a2enmod rewrite filter deflate headers expires mod_version proxy_http.load
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 127.0.1.1 for ServerName
do not worry, it’s not important.
Go to top
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:
apt-get install php5 php5-mysql libapache2-mod-php5 php5-curl php5-json
apt-get install screen
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
Optionally, ActiveMQ tar.gz file downloaded at the beginning is not necessary, and can be removed:
Differently from ActiveMQ, Redis will automatically start on boot.
apt-get install redis-server
Make redis listen on all ports
sed -i 's/bind 127.0.0.1/bind 0.0.0.0/g' /etc/redis/redis.conf
Done! You can launch it by typing
service redis-server restart
Node.js is necessary to have a realtime chat within Matecat. Install it and its Package Manager with:
curl -sL https://deb.nodesource.com/setup_6.x | 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
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
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:
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
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 https://github.com/matecat/Matecat.git cattool
The above will create the directory cat tool and will download all Matecat codebase in it. Go to top
Navigate to the configuration directory:
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
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
Navigate to the directory
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:
And customize the default settings. Finally, save and close the editor.
Enable the web application in Apache with the following commands:
mv /home/matecat/cattool/INSTALL/matecat-vhost.conf /etc/apache2/sites-available
Go to your matecat root folder in order to install PHP composer packages
php -r "readfile('https://getcomposer.org/installer');" | 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
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
Move to the Grunt configuration folder:
Prepare the environment and deploy the source code
Move to the Node.js configuration folder:
Create the configuration file, out of the sample one
cp config.ini.sample config.ini
And prepare the environment
This configuration works out of the box, with very default settings. Please edit the config.ini file you just created to customize your settings
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
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
Configure the number of workers (each worker takes 13M of memory, on average)
echo '25' > .num_processes
Start fast Analysis and TM Analysis 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/restartAnalysis.sh" >> /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/
Run Node.js server in a screen with the following command:
screen -d -m -S 'node' node /home/matecat/cattool/nodejs/server.js
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:
- 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
- click on your newly created project
- select “APIs & auth” on left sidebar
- scroll down the list to “Google+ API” and switch the status of ON
- go back to left sidebar and, under “APIs & auth” menu, select “Credentials“
- click on “Create new client ID” buttonu
- under APPLICATION TYPE, select “Web application” option
- 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
- click on “Create client ID“. Take note of the “Client ID” and a “Client secret” you just obtained
- go back to left sidebar and, under “APIs & auth” menu, select “Consent screen“
- under PRODUCT NAME, choose a meaningful name (for example, Matecat)
- scroll down the page and click “Save“
- Finally, edit the file ~/cattool/inc/oauth_config.ini.sample, replacing the default parameters with those obtained in the previous step:
- OAUTH_CLIENT_ID with your client ID
- OAUTH_CLIENT_SECRET with your client secret
- OAUTH_CLIENT_APP_NAME with your custom app name,or leave Matecat
- save the file as oauth_config.ini
- 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.
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:
- 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.
- Click the subscribe button of your preferred plan and complete the subscription process.
- 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”).
- In the application page click on the “Get the keys” button on the right, near the top, then copy your key.
- 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:
[production] DB_SERVER = "localhost" DB_DATABASE = "matecat" ; ... ; Filters Configuration FILTERS_ADDRESS = https://translated-matecat-filters-v1.p.mashape.com FILTERS_RAPIDAPI_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 filters.matecat.com.
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