tryton-server for Debian
========================

Automated/guided setup
======================

There exist several packages facilitating the setup of a production
environment of a Tryton server.

  * tryton-server-postgresql

    This package helps in the creation and setup of a PostgreSQL database
    for the Tryton server.

    Note: To avoid the repeated input of the postgresql admin password for
    remote installations it could be a good idea to install dbconfig-common
    beforeheand with
    $ sudo apt install dbconfig-common
    and configure /etc/dbconfig-common/config with
    dbc_remember_admin_pass='true'

  * tryton-server-uwsgi

    This package helps in the creation and setup of a uWSGI frontend/backend
    for the Tryton server. Additionally it allows one to configure
    uWSGI daemons for Tryton workers and cron.
    It is recommended to run the Tryton server with a production ready 
    WSGI server instead of the integrated simple development server from 
    'werkzeug'.
    The uWSGI configuration created by this package offers access by the 
    uWSGI and/or the HTTP protocol. For small sites that are not exposed
    to the internet this may already cover your needs, otherwise have a
    look at package tryton-server-nginx to run the uWSGI server behind a
    dedicated reverse proxy.

  * tryton-server-nginx

    This package helps in the creation and setup of a Nginx frontend
    for the Tryton uWSGI server.
    It offers the automatic registration of a configured domain with
    Letsenscrypt.

  * tryton-server-all-in-one

    This package makes use of all the above packages to setup a 
    ready-to-use production grade Tryton server environment including 
    a database filled in with primary static data like countries, 
    currencies and postal codes.


At the end of the automated/guided setup of Tryton in Debian, the Tryton server
will be ready to accept connections from tryton-client or tryton-proteus and is
ready for setup of the Tryton database.

tryton-client provides a GUI to access the server. tryton-client can be run on
the server or remotely. For connection parameters see below.

On the first login or after the activation of modules the admin will be
presented a wizard that will guide through the necessary steps depending
on the installed/activated modules like
  - selection of the languages to use in the database
  - creation of other users
  - creation of a company
  - creation of an account chart and selection of the default accounts
  - selection and activation of Tryton modules that shall be used in this database.
  - evtl. configuration for the activated modules

Some of the required settings are asked for configuration directly after the activation of
modules. It is nevertheless a good idea to also search in relevant module settings for items
that can additionally be configured.

While tryton-client provides also facilities for simple CSV imports or exports as an alternative
tryton-proteus provides a Python developer interface on the command line which can be used
to automate several tasks like module activation, configuration and data population using
Python scripts, for example to script data imports, data migrations or to meet corporate disaster
recovery requirements.

An overview of the complete documentation and especially an aggregated description of the
existing modules can be found on readthedocs.io at https://docs.tryton.org.

If you have any questions further information can be found in the Tryton forum at
https://discuss.tryton.org.


Connection parameters
=====================

  * trytond listens by default on port 8000 (jsonrpc). If you need to change
    this, edit /etc/tryton/trytond.conf in the section [web].

    Example:
    - Host: <the_trytond_host>
    - Database: <tryton>
    - Username: admin
    - Password: <admin>

  * tryton-server-uwsgi
    The uWSGI server listens per default on 8000 (http) and 8001 (uwsgi).
    Thus you connect with the Tryton client with just the same parameters as
    to the native trytond.

    Example:
    - Host: <the_uwsgi_host>
    - Database: <tryton>
    - Username: admin
    - Password: <admin>

  * tryton-server-nginx
    The nginx server listens per default on 80 (http) and/or
    if configured with certbot 443 (https).
    Thus you connect with the Tryton client with the following parameters:

    Example:
    - Host: <the_nginx_host>:80
    - Database: <tryton>
    - Username: admin
    - Password: <admin>

    Example:
    - Host: <the_nginx_host>:443
    - Database: <tryton>
    - Username: admin
    - Password: <admin>

    IMPORTANT:
    In case you didn't provide an admin password during the installation
    process (e.g. non-interactive setup) you can reset the password on the
    command line with
    $ sudo -u tryton trytond-admin -c /etc/tryton/trytond.conf --password -d <your_database_name>


Important Notes
===============

Please be aware of the following things:

  * Only the same major version of Tryton client and Tryton server can connect.

  * There exist two sorts of users/passwords not to be confounded.
    According to the layers
    - the server connects to the database via a user/password (or unix socket) subsequently
      called the *database password*
    - the clients connect to the server via a user/password subsequently called the
      *login password*. Thus each Tryton database will have its own admin (and usually
      other application users) with login password stored in the database itself.

  * The server (trytond) must have read access to its configuration file,
    otherwise it will start with internal defaults.
    The postinst script will (re)set ownership to
    the system user running trytond and correct the permissions on the standard
    configuration file (/etc/tryton/trytond.conf), if not otherwise stated by
    means of dpkg-statoverride.

  * The fingerprint of connected servers is stored in the clients
    known_hosts file. When a server is changed for its SSL usage, the client
    will refuse to reconnect to this server. Removing the according line
    from ~/.config/tryton/<version>/known_hosts will allow one to connect to
    the server again.
  
  * Activation of modules in the database can be performed server side with trytond-admin
    or from the Administration Panel of the client.
    Note: If a Tryton module is *installed* in the system it is not
    automatically *activated* in the database. This must be performed
    explicitly per database.
  

Upgrade
-------

  * Once you have upgraded to a new major version (second number of the
    version string) you have to update your database(s).

    While usually migrations between major versions are fully supported, it is
    generally required to check the migration page of the upstream project at
    https://discuss.tryton.org/c/migration for any manual action to take before or
    after the upgrade process.
    
    After the categorically recommended backup do:

    $ sudo -u tryton trytond-admin -v -c /etc/tryton/trytond.conf --all -d <your_database_name>

    Remember to replace tryton with the name of your database.

    Do not forget to restart all manually configured services.


Manual setup
============

Preparing the database
----------------------

Tryton uses a Relational Database Management System (RDBMS) to store data. The
preferred RDBMS for Tryton is PostgreSQL.

You have to setup this database manually. Here is a short explanation how to
achieve this (you need to execute all commands as root):

  * Making sure, PostgreSQL is running:

    $ sudo service postgresql* restart

    Note: If PostgreSQL runs on another machine than the Tryton server, make sure
    you have setup database password authentication. Please refer to the
    PostgreSQL manual how to do this. If they run on the same machine, connection
    via local sockets is preferred and you are done with the default configuration
    of the PostgreSQL package.

  * Creating the database user:

    $ sudo -u postgres createuser --createdb --no-createrole --no-superuser \
        --pwprompt tryton

    You have to enter
    * a password for the future database user (this will be used later in the
      setup of the database URI in /etc/tryton/trytond.conf as password)
    * confirm it
    * and finally enter the password of the postgres superuser.

    Note: If you want to run the database as another user than 'tryton', you
    need to replace 'tryton' above with the user you want to use instead.

Preparing the Tryton server
---------------------------

  * Setting up the Tryton server:

    Note: The server comes with five binaries:
    - trytond (runs the server)
      Note: It is not recommended to use this development server in production.
      You should run the server under a robust WSGI backend
      (s.a. tryton-server-uwsgi)

    - trytond-admin (used for the administration tasks of the server, e.g. the
      database administration)
    
    - trytond-console (used for inspection and actions from the command line)
    
    - trytond-cron (runs the cron part of the server, should only be started
      once per configuration)
      also be activated in the configuration file)
      SysVinit:
      - Configure the databases you wish to run the cron job on in /etc/default/tryton-server
      - Enable the init script with update-rc.d tryton-server-cron enable
      Systemd:
      - Enable the cron job for <database> with
        systemctl enable tryton-server-cron@<database>.service
    
    - trytond-stat (used to get statistics for a running instance)
    
    - trytond-worker (runs dedicated workers to handle task queues, this must
      SysVinit:
      - Configure the databases you wish to run the worker job on in /etc/default/tryton-server
      - Enable the init script with update-rc.d tryton-server-worker enable
      Systemd:
      - Enable the worker job for <database> with
        systemctl enable tryton-server-worker@<database>.service
      Note: The current default scripts start as many workers as CPUs are detected.
      If you want to limit the number of the workers add the parameter -n <number>
      to the command.

    Adjust /etc/tryton/trytond.conf to reflect the setup of your system by using
    the database user and password from step 1 for the database URI.

  * If the Tryton server shall listen on some external interface (i.e. shall be
    available for clients connecting from other machines), change the listen
    parameter in the web section accordingly.

  * If the Tryton server is listening on external interfaces, it is highly
    recommended to enable SSL for the connection. Preferably this is delegated
    to a proxy (s. comments in trytond.conf, tryton-server-nginx).

    Note: The package is prepared to use the snakeoil certfificates from
    the ssl-cert package. If you are installing the ssl-cert package after
    the tryton-server package, take care to add the tryton user to the
    ssl-cert group with

    $ sudo adduser tryton ssl-cert

  * trytond listens by default on port 8000 (jsonrpc). If you need to change
    this, edit /etc/tryton/trytond.conf in the section [web].

  * trytond in its upstream configuration listens by default to the localhost
    interface. If you want to change this default to listen on all interfaces,
    edit /etc/tryton/trytond.conf in the section [web].

  * Restarting trytond:

    $ sudo service tryton-server restart
    $ sudo service tryton-server-cron restart

    Now you are ready to connect with a client, e.g. tryton-client.

  * The start of Tryton cron has to be enabled and configured with the target
    database with appropriate start scripts (sysvinit, systemd).
    Have a look at tryton-server-cron@.service.

  * The start of Tryton workers has to be enabled and configured with the target
    database in the configuration file (s. /etc/tryton/trytond.conf) *and*
    with approprate scripts (sysvinit, systemd).
    Have a look at tryton-server-worker@.service.



Creating the database
---------------------

On the command line:

  * Creating the database:

    $ sudo -u postgres createdb --encoding=UNICODE --owner=tryton tryton

    Note: Use your database user for tryton as owner of the database, and enter
    a name for the database (here as default: tryton).

  * Initializing the database:

    $ sudo -u tryton trytond-admin -v -c /etc/tryton/trytond.conf --all -d <your_database_name>

    Note: Use the database name you chose in the previous step (here as default: tryton).
    You will be asked for the admin password and email for this database.

    As result you will have a bare Tryton database with the base modules installed.
  
  * Activating a new language on an existing database:

    $ sudo -u tryton trytond-admin -v -c /etc/tryton/trytond.conf --all -d <your_database_name> -l <language_code>

    Available language codes are at the time of writing:
    en, bg, ca, cs, de, es, es_419, fr, hu_HU, it_IT, lo, lt, nl, pt_BR, ru, sl, zh_CN


 -- Mathias Behrle <mbehrle@debian.org>  Mi, 08 Jun 2022 12:00:00 +0100
