The server part of Cyclotis is a set of Perl/PSGI web applications, Perl and SQL scripts, based on PostgreSQL version 8.4 or later. Any operating system (including linux, BSD, or maybe Windows) which can host PostgreSQL 8.4 (or recommended, almost 9.2) and Perl 5.10 should be able to host a Cyclotis server, but it has mainly be tested on linux distributions Red Hat Entreprise 6 and 7, and Debian 8 or 9.

In this tutorial we will try to install our tools in an existing distribution. Installation of dependancies, including Postgres, are minimally detailed, as it can depend on your distribution. Installation of linux distribution

Install Postgres

apt-get install postgresql \
    postgresql-client postgresql-client-common \
    postgresql-common postgresql-contrib

postgresql-setup --initdb
systemctl start postgresql
systemctl enable postgresql 

It is also possible to use one or more distinct instances of Postgres server : in Debian this is easier with pg_createcluster, while in other distributions it is to be done manually. For this tutorial, we will remain with default server.

Install Perl

In most linux or bsd distributions, the core interpreter is already installed, and unless your distribution was made before 2010, you probably have a sufficient version. Also add the following Perl packages:

• DBI (generic access to databases)
• DBD::Pg (the Postgres-specific Perl driver)

To do so:

Install the SQL package

One difficulty with our server is that the creation of Cyclotis/Postgresql database has to be done with Postgres's admin rights (the ones of the postgres user, not from the Unix root!), but only for the initial creation, not to add memories later. This constraint disappears if you use Postgres 13 or later, but for the moment, let's consider it is still valid. For that tutorial we will put all memories in the same Postgres database, to make it simpler.

1. Give to Unix "postgres" user execution rights to the SQL scripts (you can remove later): chmod a+x db/*.pl
2. Connect as postgres (su postgres), without changing environment.
3. Create postgres users tb-admin and tb-user : createuser tb-admin; createuser tb-user.
   The first one will create and delete memories, the second will use them
4. Create the catalog (the database, if you prefer): cd SQL/db; perl dbcreator.pl create-db postgres#tb-admin@/MyCyclotis (in this syntax, we create database "MyCyclotis" which will be managed by user "tb-admin". User "postgres" is only used during creation. Being connected as "postgres", the server will not require password.
5. Exit postgres user, not used anymore (exit)

Now we can create a first memory:

• Create the memory: cd SQL/db; perl dbcreator.pl create-table tb-admin@/MyCyclotis MyFirstMemory (for db, same syntax as before except that we do not need "postgres" user anymore; Then the name of the memory to be created).

At this step we can consider that the server is usable, but not easily:

• You can continue to create memories with the SQL scripts, but only from an ssh connection to the server itself. In a next step, we will install the web creator, which is an HTML interface, not especially beautiful but which may be enough to begin a real usage of the server
• It is already possible to use the memories from Trados or OmegaT if the Postgres server accepts IP connections (but it is not the case by default). If you want to use this solution:
  • check in postgres.conf that the parameter listen_adresses is set either to all, or to a correct set of IP values
  • check in pg_hba.conf that there are values with host as first parameter and correct set of IP values
  • ensure that Postgres already contains users you want to allow to be connected from a client (in the tutorial, that is the role of the tb-user user: ensure it has a passowd!)
  • be sure the port 5432 is not blocked for external computers by your firewall !!!

  However, direct acces is the fastest method but not the most secure. In the following steps we will use HTTP proxy, which enables usage of the memories without opening Postgres port 5432 at all.

Install Perl/Dancer framework

In Debian and Red-Hat based distributions, package should be available:

If not, use the CPAN (note: you may need to install gcc before!):

perl -MCPAN -e shell
install Dancer
install Dancer::Plugin::Database

warning: actually our applications are based on Dancer 1, not on Dancer 2 which still seems in Beta and is not compatible.

Install web creator

The web creator is a small HTML application which enables to create, list and delete Cyclotis memories, based on the previously installed Perl+SQL scripts but without the need to have an SSH access to the server.

Download and extract archive from here, then open the config.yml file:

• First, configure which database to be connected to; for this tutorial, probably "localhost", port "5432", catalog "MyCyclotis", user "tb-admin" without password.
• Then, where the SQL scripts are located. Be sure that the user which runs the web application has execution rights to these scripts, almost to dbcreator.pl
• For the simplicity of this tutorial, let's remove any other parameter, including "parent", "possible-values", "list", etc: for the moment, we create a memory per project when needed, that's all. You can learn later about how the application can be more customized
• Now you can start the application: perl web-creator-html.pl. The server will tell you which port it is listening on (usually 5000 depending on how Dancer has been installed).
• Open your browser (http://your-host:your-port/, for example http://my-host:5000/) and you should see list of existing memories, probably only one for the moment. In this application you can create or delete memories at any moment : this is for immediate use, not for highly secured server!
• If the browser does not show the list but seems to go to an infinite loop, it may mean that the port selected by the applicatio is blocked by the firewall. In this case, try another port, for example perl web-creator-html.pl

Here we made basic installation of the server, with no security. This server can also be used inside any perl-compliant web server, in particular Apache/mod_perl. If you need security, better configure it in the Apache configuration.

Install REST server

Contrarily to previous server, this one is not a web/html interface but a web service to be used by the clients, namely by OmegaT and Trados via their respective plugins. As already explained, it is also possible (but less secure and harder to configure) to do direct access without this REST service, but only if port 5432 is open and if Postgres is correctly configured.

Download and extract archive from here, then open the file rest/config.yml:

• First, configure which database to be connected to; for this tutorial, probably "localhost", port "5432", catalog "MyCyclotis", user "tb-user"
• The file given in the archive contains lot of parameters and for most of them, multiple samples. Remove the parameters you don't want to use, and keep only one value for the ones which are meaningful for you
• Now you can start the application: perl rest/cyclotis-rest-api.pl
  The server will tell you which port it is listening on (usually 5000 depending on how Dancer is installed).
• If the server refuses to start, saying that the port is already used: either stop the previous application (web creator), or select another port: perl rest/cyclotis-rest-api.pl -p 8081
• Open your browser (http://your-host:your-port/, for example http://my-host:5000/) and you should a small welcome html page. This page is only here to enable checking that the server works: after that, it will be called only by Trados and OmegaT, and use XML, JSON or CSV messages in REST protocol
• If the browser does not show the page but seems to go to an infinite loop, it may mean that the port selected by the applicatio is blocked by the firewall. In this case, try another port, for example perl web-creator-html.pl

As for the previous server, here we did basic configuration, but other possibilities, like Apache/mod_perl, are also available. If you want to run all applications in the same port, you cannot do it with the basic Dancer server, but you can do it with Apache, either using it as a proxy or configuring directories via directive. Apache is also recommended for intensive use of the services, especially the REST server: the basic server delivered with Dancer as default is really only for development purpose.

We are perfectly aware that all of this is not easy. We try to make it progressively simpler, but that is an hard work (developers, if you have ideas...). In the meantime, if it is too difficult to you, use our already configured SaaS server instead!