.. contents::
======================
Installation and setup
======================
Eints is written in `Python 3 `_. Its software uses the `GPL V2
`_. For stand-alone use (which is
useful for development and testing), no other software is needed.
Internally, it uses:
- `Bottle `_, a Python framework for writing web applications.
- Location: webtranslate/bottle.py
- Licensed under `MIT License `_
- `Twitter Boostrap `_, a CSS, JS and glyphicon framework
for web application user interfaces.
- Locations: static/css static/img static/js
- Code licensed under `Apache License v2.0 `_,
- Documentation licensed under `CC BY 3.0 `_.
- Glyphicons Free licensed under `CC BY 3.0 `_.
- `WooCons #1 `_, an icon library.
- Location: static/img/woocons1
- Licensed under `GPL v3 `_
The Eints repository includes files of the above projects for your
convenience. They are however not part of Eints.
Setup
=====
After downloading and unpacking, Eints needs to be configured:
- A :ref:`server_configuration` must be set up.
- :ref:`page_access_rights` must be set up.
If the authentication in the ``config.xml`` file is set to ``development``,
additional configuration file must be set up:
- :ref:`project_owners_translators` must be set up.
- :ref:`users_passwords` must be set up.
If the authentication in the ``config.xml`` file is set to ``redmine`` or
``ldap``, the latter information is retrieved from the Redmine data base
or LDAP respectively, as explained in :ref:`redmine_configuration_setup`
and :ref:`ldap_configuration_setup`.
.. _server_configuration:
Server configuration
--------------------
The global configuration settings are in ``config.xml``. It has the following
entries:
Note that Eints is not thread-safe, trying to use it with multiple threads
will fail to work properly.
Server setup
~~~~~~~~~~~~
The following configuration fields exist for the general server set up.
*server-mode*
Mode of the server, must be either ``development``, ``production`` or
``mod_wsgi``. The former two will start a bottle web server. In
*development* mode, errors that happen in the server process are copied into
the generated html page. The latter allows deployment via apache's mod_wsgi.
See :ref:`apache_mod_wsgi` for an example configuration with mod_wsgi.
*server-host*
Name of the host that should provides the Eints service.
*server-port*
Port number of the host that should provide the Eints service.
*authentication*
Method of authentication. Currently supported forms are:
* ``development`` which uses local files for everything, or
* ``redmine`` which hooks into the `Redmine `_ software for
roles and users.
* ``ldap`` which queries an LDAP server for authentication and roles.
Eints uses basic authentication to authenticate users. For this reason, the
Eints service should be remotely accessible only through a secure connection.
.. XXX links and references
.. _apache_mod_wsgi:
Server setup with apache's mod_wsgi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Below is an example apache2 configuration assuming eints to reside
in the directory ``/home/eints/eints``::
WSGIPythonPath /home/eints/eints
ServerAdmin webmaster@localhost
WSGIDaemonProcess eints user=eints group=eints processes=1 threads=1 home=/home/eints/eints
WSGIScriptAlias / /home/eints/eints/app.wsgi
WSGIPassAuthorization On
DocumentRoot /var/www
WSGIProcessGroup eints
WSGIApplicationGroup %{GLOBAL}
Order allow,deny
allow from all
ErrorLog ${APACHE_LOG_DIR}/error.log
# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
LogLevel warn
CustomLog ${APACHE_LOG_DIR}/access.log combined
Project data setup
~~~~~~~~~~~~~~~~~~
The following configuration fields exist to define how project data is
treated.
*stable-languages*
Path to the directory with meta-information of 'stable' languages (that is,
languages with a sufficient number of translators).
*unstable-languages*
Path to the directory with meta-information of 'unstable' languages (that is,
languages generally lacking translators). Optional configuration.
*project-root*
Root directory of the data files for each project, including the backup
files.
*project-cache*
Eints loads project data files when needed. To reduce memory requirements,
this setting controls how many data files it may keep in memory.
*project-types*
Eints understands three types of projects, ``openttd``, ``game-script``, and
``newgrf``. Each has a different set of known string commands. In this
configuration field, you can list the project types that should be allowed
(separated by white space).
*storage-format*
This configuration field controls the storage format used for new
translation projects.
The ``one-file`` format stores all information about a project in a single
file. It is simple to handle, having all information at one place.
For bigger projects, the format may become too unwieldy to handle.
Internally, the file is completely created before storage, and memory
requirements can become huge. The ``split-languages`` format aims to solve
that. Instead of a file, the project data all goes into a directory. Within
the directory, there is a ``project_data.xml`` file, and one for each
language. Files are only written when modified.
*data-format*
This configuration field controls whether XML or JSON is used for storage.
It only affects new projects. The field contains either ``xml`` (for XML
data format) or ``json`` (for JSON data format).
XML format has more features, but tends to grow fast in memory requirements
with bigger projects. JSON is better for big projects (needs less memory),
but lacks (at the time of writing this) support for sharing text strings.
That doesn't hurt much if you use ``split-languages`` for the
*storage-format* field, as normally, there are not many string shared within
a single language.
*language-file-size*
Eints can download `NML ` language files.
This setting control the maximum size in bytes of such files.
*num-backup-files*
When the data of a project is changed, Eints writes a new copy of the
project data to disk. This setting controls how many previous versions are
kept.
*max-num-changes*
Eints enables changing of strings in translations. For reference purposes, a
number of previous texts for each string (in each language in each project)
are kept. This setting controls how many can exist at most. Keep in mind
that the last uploaded string is always kept to allow comparing with the
next upload.
*min-num-changes*
Controls the minimum number of texts to keep for each string. Should be at
least ``2``. (One for the last uploaded text, and one for the newest
translation.)
*change-stable-age*
When a string is being changed, the change is considered 'unstable', and will be kept
for a while. This setting controls when such a change is sufficiently old to
consider it 'stable', so it may get deleted if the string count is above
``min-num-changes``.
When uploading language files from NML, Eints uses the available strings to
detect whether changes occurred in the file. The ``min-num-changes`` and
``change-stable-age`` values should be chosen such that previously uploaded
information is still available when downloading updates.
.. _redmine_configuration_setup:
Redmine configuration setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If Eints *authentication* is using ``redmine``, the redmine part of the
configuration should also be filled in.
*db-type*
Type of data base used by Redmine.
*db-schema*
Postgress sometimes needs a search path to find its schema.
*db-user*
Accoutn which gives read access to the Redmine data base.
*db-password*
Password of the ``db-user`` entry to get read access to the Redmine data
base.
*db-host*
Name of the host to contact for accessing the data base.
*db-port*
Port number of the ``db-host`` to contact.
Redmine roles setup
~~~~~~~~~~~~~~~~~~~
Eints uses a project owner and translator roles to provide access to its web
pages. These roles are mapped to Redmine roles, so you can setup access control
from the Redmine interface.
*owner-role*
Name of the Redmine role to denote the user(s) which are considered
'project owner' for an Eints project.
*translator-role*
Name of the Redmine role to denote the user(s) which are considered to be
a translator for one language.
A translator role must be defined for each language that is used in Eints.
Each Eints role may map to the same Redmine role however.
Note that project owner access implies translator access in Eints.
Any page accessible to a translator is also accessible by the owner of the
project.
.. _ldap_configuration_setup:
LDAP configuration setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~
If Eints *authentication* is using ``LDAP``, the LDAP part of the
configuration should also be filled in.
*host*
URL to LDAP server, optionally including a port number.
*basedn-users*
Base DN for users in the LDAP tree. User objects are looked up
via 'cn:Username' directly subordinate to the base DN.
*basedn-groups*
Base DN for groups in the LDAP tree. Group objects are looked up
via 'cn:Groupname' directly subordinate to the base DN:
LDAP roles setup
~~~~~~~~~~~~~~~~~~~
Eints uses a project owner and translator roles to provide access to its web
pages. These roles are mapped to posixGroup memberships in LDAP.
Note, that the roles are language specific, but not project specific. All
translators have access too all projects in Eints. The 'OWNER' role is an
administrator role, with access to all projects.
*owner-group*
CN of the posixGroup to denote the user(s) which are considered
'project owner' for *all* Eints project.
*translator-group*
CN of the posixGroup to denote the user(s) which are considered to be
a translator for one language.
A translator group must be defined for each language that is used in Eints.
Each Eints role may map to the same posixGroup however.
The groups are not project specific, a translator always has access to all
projects.
Note that project owner access implies translator access in Eints.
Any page accessible to a translator is also accessible by the owner of the
project.
.. _page_access_rights:
Page access rights
------------------
The ``rights.dat`` file defines who can access the data. It inspects paths of
web pages being accessed, and checks whether the user performing the operation
should be allowed to proceed.
The file is a list of access rules, that associates users and paths with the
right to access. The general form of a rule is::
+/-
The ``+/-`` at the first access rule that matches with the user and the path
decides access. The ``+`` means to give access, ``-`` means deny access.
For readability, the file can also have empty lines, and comment lines (a line
starting with ``#`` in the first column).
A ```` can be
- A literal username (not recommended),
- The ``*`` wildcard, matching everybody,
- ``SOMEONE``, matching unauthenticated users,
- ``OWNER``, a user denoted as owner of the project that is accessed through
the path.
- ``TRANSLATOR``, a user that is registered as translator for a language in a
project, for paths that deal with languages. Obviously being an ``OWNER``
implies being an ``TRANSLATOR`` for all languages in the project.
A looks a lot like the paths used by Eints for the URI of the web-pages. A
path in this file however always has four elements, namely *action*, *project*, *language*,
and *operation*. Each of the elements is a name, the value ``*`` (to denote
its value is not relevant in matching), or the value ``-`` (to denote the
value does not exist).
The *action* is the same as the first component in the URI, except that the
root page uses ``root`` as action. The following actions exist:
- ``root``, the root page,
- ``projects``, the overview page containing all projects,
- ``project``, the overview page of a single project,
- ``language``, the overview page of a language in a project,
- ``string``, the edit page of a single string in a single translation
language,
- ``upload``, the page to upload language files into Eints,
- ``download``, the download page for getting new language files from Eints,
and
- ``delete``, the page to delete a language.
The *project* and *language* elements are the name of the project and name of
the language respectively. Usually these are not interesting, access control
is handled with ``OWNER`` and ``TRANSLATOR`` users.
The *operation* element is either ``read`` or ``add``.
For reference purposes, below is an example access rights file::
# Root, project overview, and download pages are readable by all
* + /root/-/-/read
# Unauthenticated users don't get any further
SOMEONE - /*/*/*/*
# First pages of project creation can be used by anyone (these pages have no
# project to authenticate against).
* + /newproject/-/-/read
* + /createproject/-/-/add
# Only the owner can create a project.
OWNER + /makeproject/*/-/add
# Authenticated users (of a project) can see the projects, see each project, download a
# language, and get an overview of a language in a project.
* + /projects/-/-/read
* + /project/*/-/read
* + /download-list/*/*/read
* + /download/*/*/read
* + /language/*/*/read
# Strings editing
OWNER + /string/*/*/*
TRANSLATOR + /string/*/*/*
# Language file uploading, language deletion and creation
OWNER + /upload/*/-/*
OWNER + /delete/*/*/*
OWNER + /newlanguage/*/-/*
OWNER + /projsettings/*/-/*
.. _project_owners_translators:
Project owners and translators
------------------------------
In the above section, user categories ``OWNER`` and ``TRANSLATOR`` may be used to
define who can access certain pages.
If the ``authentication`` entry in ``config.xml`` is set to *redmine* or *ldap*,
the Redmine data base or LDAP are queried for membership of the roles. If the
``authentication`` entry is set to *development*, a local file is used,
explained below.
Membership of a user in these categories is decided in the ``projects.dat``
file. It is a INI file, where the section name is the name of the project, the
keys of a section are the languages, and the values are the names of the users
separated by spaces or commas.
The special 'language' ``owner`` is used to denote project ownership.
An example::
[eints]
owner = alberth, andythenorth
nl_NL = alberth
Here, the ``eints`` project is defined (always lowercase), with two owners,
and one translator for the Dutch language.
(Note that since an owner also has translator access, the final line is not
needed in this example.)
.. _users_passwords:
Users
-----
Users send authentication information using standard HTTP basic authentication
to the web server. As such, it is highly recommended to use the ``https``
protocol for the translator service.
If the ``authentication`` entry in ``config.xml`` is set to *redmine* or *ldap*,
the Redmine data base or LDAP are queried for user authentication. If the
``authentication`` entry is set to *development*, a local file is used. In the
latter case users and their passwords are stored in plain text in
``users.dat``. Obviously, this is not secure in any way. It should never be
used to store important authentication information. The ``editsilly`` program
can add, update, and remove users from the file, for example
::
./editsilly admin
would create or change the ``admin`` account.
.. vim: sw=4 sts=4 tw=78 spell