root/docs/intro/install.txt @ 648:80458a875eac

.. _intro-install:

Quick install guide
===================

Before you can use Transifex, you'll need to get it installed. This guide 
will guide you to a simple, minimal installation that'll work while you 
walk through the introduction.

Installing Python
-----------------

Being a Python Web tool, Transifex requires Python. We recommend 
installing Python 2.5 or later.

Get Python at http://www.python.org. If you're running Linux or Mac OS X, 
you probably already have it installed.

You can verify that Python's installed by typing ``python`` from your 
shell; you should see something like::

    Python 2.5.1 (r251:54863, Jun 15 2008, 18:24:51)
    [GCC 4.3.0 20080428 (Red Hat 4.3.0-8)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>>


Installing the Version Control Systems - VCS
--------------------------------------------

To run Transifex you need some VCS. Depending of which ones you want 
to use, you will need to install some of the following packages:

* Bazaar (bzr)
* CVS (cvs)
* Git (git)
* Mercurial (hg)
* Subversion (svn)

On Fedora you can run the following command to install all those VCS::

    yum install cvs subversion pysvn mercurial git bzr bzrtools 

If you're enabling the tarball support, you also need urlgrabber::

    yum install python-urlgrabber 


Installing Django
-----------------

Transifex is developed on top of a Python Web Framework called Django. We 
recommend installing Django 1.0. You can get more information about how
to install Django in your system from the official Django documentation.

Usually you can use the package your distribution provides you, or you can
even use `easy_install` to setup the package. On Fedora you can just run::

    yum install Django

.. _install-django-deps:


Installing Python dependencies
------------------------------

This is the generic method for creating a development environment for
Transifex. We strongly suggest running those commands inside a virtualenv
environment instead of running them as root. For an example of a Virtualenv
setup, take a look at the `Virtualenv example`_ wiki page. You can also
install some of these dependencies as packages in your distribution, if they
are available.

.. code-block:: bash

    easy_install Markdown httplib2 pygments polib
    easy_install Django python-openid django-authopenid django-pagination
    easy_install django-notification
    easy_install -f http://transifex.org/files/deps/ contact_form tagging django_evolution userprofile


Installing translation-specific packages
----------------------------------------

Transifex requires a couple of standard packages to support translations.
Currently these are the following.:

* gettext (standard Internationalization library)
* intltool (for dynamic ``POT``-file generation)

On Fedora you can just run::

    yum install gettext intltool


A note on ``PythonPath``
~~~~~~~~~~~~~~~~~~~~~~~~

These applications can be installed anywhere on your system, as long as Python
can find them. Python uses the ``PythonPath`` environment variable for this.
The value you use for ``PythonPath`` should include the parent directories of
all the modules you are going to import in your application. It should also
include the parent directory of Transifex itself.
This is exactly the same situation as
setting the Python path for interactive usage. Whenever you try to import
something, Python will run through all the directories in ``sys.path`` in turn,
from first to last, and try to import from each directory until one succeeds.

An example might make this clearer. Suppose you have some applications under
``/usr/local/django-apps/`` (for example, ``/usr/local/django-apps/weblog/`` and
so forth), your settings file is at ``/var/www/mysite/settings.py`` and you have
specified DJANGO_SETTINGS_MODULE_ as in the above
example. In this case, you would need to write your ``PythonPath`` directive
as::

    PythonPath "['/usr/local/django-apps/', '/var/www'] + sys.path"

With this path, ``import weblog`` and ``import mysite.settings`` will both
work. If you had ``import blogroll`` in your code somewhere and ``blogroll``
lived under the ``weblog/`` directory, you would *also* need to add
``/usr/local/django-apps/weblog/`` to your ``PythonPath``. Remember: the
**parent directories** of anything you import directly must be on the Python
path.

.. _DJANGO_SETTINGS_MODULE: http://docs.djangoproject.com/en/dev/topics/settings/#django-settings-module


Installing Transifex
--------------------

You'll need to get Transifex, initialize its database and optionally import
some sample data.

Get Transifex
~~~~~~~~~~~~~

You can get the source code in a number of ways.

Stable releases are available from the following location(s):

- http://transifex.org/files/
- http://pypi.python.org/pypi/transifex 

Soon, Tx will land in a yum repo near you, and you'll be able to
install it with something like ``yum install transifex``. See also the
README file in the root of your source.

Development version
+++++++++++++++++++

The current development version of Transifex can be fetched by cloning the
development repo::

    hg clone http://code.transifex.org/mainline

From here you can also switch to stable versions, which are tagged
appropriately.::

    hg tags
    hg update <tag>

To grab a branched development version of Transifex, you can navigate to
http://code.transifex.org/ to see the active branches. 

Initialize the database
~~~~~~~~~~~~~~~~~~~~~~~

After you have all dependencies and packages installed, the Transifex 
installation should be very simple. Customize ``settings/*.conf`` and
``urls.py`` to accommodate your server's needs.

To enable Transifex's notifications you'll need to switch the relevant setting
called ENABLE_NOTICES to ``True``.

Once you're done configuring, run inside the project directory::

    ./manage.py syncdb
    ./manage.py txcreatedirs
    ./manage.py runserver 8088

The first command will create the necessary database tables. It will also ask
you to create an admin user (superuser), who will have access to the admin panel
(by default accessible through ``/admin/``).

Fire up your browser at ``http://localhost:8088/`` and grab a cup of coffee.

.. warning::
 
    Make sure you have created in your system all the directories configured
    in your ``settings.py`` file, like the ``REPO_PATH`` for example.
    Without those paths created, the checkout for these VCS, among others will
    fail.

Import some data
~~~~~~~~~~~~~~~~

Transifex uses the fixtures feature of Django to load some initial datas
in the database. The following commands require you having run
``./manage.py syncdb`` at least once before in order for the database tables
to exist.

The following commands loads a bunch of sample data to play around with.

.. code-block:: bash

    ./manage.py loaddata txcommon/fixtures/sample_data.json
    ./manage.py loaddata txcommon/fixtures/sample_users.json

The last command created two users: 'guest' and 'editor'. The 'guest' has the
basic rights of a logged-in user of the site, while the 'editor' account has
more advanced privileges like modifying projects, etc. Together with the 'admin'
user created with the 'syncdb' step above, you should have 3 accounts now, each
with its own access level.

You can now fire up your browser to check out the newly imported data.

Note that the registered projects have not been actually checked out by
Transifex yet. To have translation files downloaded and fresh statistics
produced, run a fresh checkout::

    ./manage.py txstatsrefresh

This command is usually used in a cronjob to refresh Transifex's cache and
translation statistics every once in a while for translators.

Internationalization (i18n) support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To be able to use Transifex with a localized interface, it is necessary to
create the translations objects files (.mo) using one of the following commands,
for example:
    
.. code-block:: bash

    ./manage.py compilemessages -l pt_BR
    or
    ./manage.py compilemessages --all


Customizing your Transifex instance
-----------------------------------

Site Domain and Name
~~~~~~~~~~~~~~~~~~~~

Transifex leverages the power of Django's Sites_ framework to make it easy
to have instances of Transifex on differnet domains using the same models
and database.

Upon installation, a single website is created in the database called
'example.com'. This value is used in a number of places, including emails sent
by the system. You can customize this value in two ways:

* Using the `Django admin panel`_: By default Transifex comes with a handy
  admin panel. This is mounted by default at ``/admin/`` (this value can be
  changed from your settings file.
  
  Login to the admin panel using the credentials you created during the
  database creation step. You'll find the 'example.com' entry in the ``Sites``
  model, which you can edit to your needs.

* Using the command line::

    from django.contrib.sites.models import Site
    current_site = Site.objects.get_current()
    current_site.name = 'Transifex'
    current_site.domain = 'mydomain.com'
    current_site.save()

User Interface
~~~~~~~~~~~~~~

The default Transifex interface lives in the ``templates`` directory and can
be customized at will.

You can also customize the theme by copying this directory to a differnet
location and updating the ``TEMPLATE_DIR`` setting with this new location.

Finally, Django supports multiple locations of template source files, which it
searches in order. Instead of copying the entire template directory, you can
simply copy particular files you'd like to override and define the
``TEMPLATE_DIR`` setting as a tuple in the order you'd like the directories
to be searched (first entry takes preference over second, etc).  


Debugging
---------

Debugging is enabled through a separete ``SETTINGS`` file, which enables some
additional applications and features. Some of these additional applications
might require installation using ``easy_install``, but you can enable any
number you want by editing the ``settings_debug.py`` file.

Some of these applications define their own models, so the first time you'll
use the file, a 'syncdb' using that file will be needed to have the respective
database tables created::
  
    ./manage.py syncdb --settings settings_debug

From that point on, you can run the debug server as follows::

    ./manage.py runserver --settings settings_debug
    

Testing
-------

For testing the whole project you can run::

    ./manage.py test

For testing a specific application inside Transifex you can run::
 
    ./manage.py test projects


.. _Sites: http://docs.djangoproject.com/en/dev/ref/contrib/sites
.. _`Django admin panel`: http://www.djangobook.com/en/1.0/chapter06/
.. _`Virtualenv example`: http://transifex.org/wiki/Development/InstallationOnCentOS_VirtaualEnv