$OpenBSD: README,v 1.2 2019/05/09 17:39:24 semarie Exp $

+-------------------------------------------------------------------------------
| Running trytond on OpenBSD
+-------------------------------------------------------------------------------

PostgreSQL is the recommended daemon for production usage. Trytond has support
for SQLite too, but intended only for testing purpose.

PostgreSQL configuration
========================

System starting ordering
------------------------
Trytond daemon should be started AFTER database daemon.
When postgresql is used, the following commands are needed:

	# rcctl enable postgresql trytond
	# rcctl order postgresql trytond


Creating a postgresql user for tryton
-------------------------------------

	# su _postgresql -c "createuser -U postgres -P tryton_user"
	Enter password for new role: tryton_user-password
	Enter it again: ...
	Password: postgres-password

When postgresql and trytond are on the same host, the config file of trytond
should contains:

	[database]
	uri = postgresql://tryton_user:tryton_user-password@/

Note that if the password contains special characters, it should be urlencoded.


Creating a new tryton database on PostgreSQL
--------------------------------------------

The database should be created using createdb(1) tool from postgresql.

	# su _postgresql -c "createdb -U postgres -O tryton_user -E UTF8 mydatabase1"
	Password: postgres-password

And it should be initialized with trytond-admin(1) tool from trytond, after the
configuration file has been configured.



Trytond configuration
=====================

Rcscripts
---------

trytond comes with 3 rcscripts:

- trytond : trytond server listening on HTTP
- trytond_cron : trytond cron service
- trytond_worker : trytond asynchronous task service
  (see http://doc.tryton.org/projects/trytond/en/5.2/topics/configuration.html#worker)

Useful flags on rcscript are:

- configuration file : `--config FILE [ FILE ...]`
- logging configuration file (ConfigParser format) : `--logconf FILE`
- database name to use : `--database DATABASE [DATABASE ...]`

By default, configuration file is at /etc/trytond/server.conf and
logging configuration at /etc/trytond/logging.conf .

Please note that `--database` is required for trytond_cron and trytond_worker,
else the daemons won't know which databases to monitor and they will do
nothing.

	# rcctl set trytond flags $(rcctl getdef trytond flags) --database mydatabase1
	# rcctl set trytond_cron flags $(rcctl getdef trytond_cron flags) --database mydatabase1
	# rcctl set trytond_worker flags $(rcctl getdef trytond_worker flags) --database mydatabase1


Configuration file
------------------

See http://doc.tryton.org/projects/trytond/en/5.2/topics/configuration.html for documentation.


Database initialisation
=======================

Once the configuration file configured, you could initialize the database using:

	# su _trytond -c "trytond-admin -v -c /etc/trytond/server.conf -d mydatabase1 --all"

it will ask you for admin email and password, and configure the database
accordingly. Please note that the database should be created first.

For more details, see http://doc.tryton.org/projects/trytond/en/5.2/topics/setup_database.html

Trytond upgrade
===============

For more details, see http://doc.tryton.org/projects/trytond/en/5.2/topics/setup_database.html#update-a-database

Minor upgrade
-------------

You should update the modules information registered in database using
filesystem information.

	# su _trytond -c "trytond-admin -v -c /etc/trytond/server.conf -d mydatabase1 --update-modules-list"

And next, start the upgrade of the modules.

	# su _trytond -c "trytond-admin -v -c /etc/trytond/server.conf -d mydatabase1 --all"


Major upgrade
-------------

Upgrade path is possible from N to N+1 version.

Follow indications at https://discuss.tryton.org/c/migration .

Please note some actions may require to be done BEFORE updating.


Customization via trytond modules
=================================

Customization on Tryton is expected to be done via installation of modules.

To easy inclusion of local modules without installing them at system level, the
recommended way is to use the per-user site-packages directory (PEP-370). For
the default user used for running `trytond` daemon (`_trytond` user), the
directory is at `/var/trytond/.local/lib/python3.8/site-packages/`.

To keep proper control on read-write directories used by `_trytond` user, you
should make the `site-packages` directory writeable only for you (and readable
by `_trytond`). As root, you could do the following:

	# chown user /var/trytond/.local/

Next, when installing a new module as user, you could temporary change the
`HOME` environment variable to run the install command.

Example of installing a module from local directory, using `setuptools`:

	$ cd path/to/my-local-tryton-module
	$ HOME=/var/trytond python3.8 ./setup.py install --user

or installing a module using pip3.8 (installable from ports):

	$ cd path/to/my-local-tryton-module
	$ HOME=/var/trytond pip3.8 install --user .

	$ HOME=/var/trytond pip3.8 install --user my-module
