doc/01_getting_started.rst

   1 ========================================
   2 Getting started with OpenERP development
   3 ========================================
   4
   5 .. toctree::
   6    :maxdepth: 1
   7
   8 Installation from sources
   9 ==========================
  10
  11 .. _getting_started_installation_source-link:
  12
  13 Source code is hosted on Launchpad_. In order to get the sources, you will need Bazaar_ to pull the source from Launchpad. Bazaar is a version control system that helps you track project history over time and collaborate efficiently. You may have to create an account on Launchpad to be able to collaborate on OpenERP development. Please refer to the Launchpad and Bazaar documentation to install and setup your development environment.
  14
  15 The running example of this section is based on an Ubuntu environment. You may have to adapt the steps according to your system. Once your working environment is ready, prepare a working directory that will contain the sources.  For a ``source`` base directory, type::
  16
  17   mkdir source;cd source
  18
  19 OpenERP provides a setup script that automatizes the tasks of creating a shared repository and getting the source code. Get the setup script of OpenERP by typing::
  20
  21   bzr cat -d lp:~openerp-dev/openerp-tools/trunk setup.sh | sh
  22
  23 This will create the following two files in your ``source`` directory::
  24
  25   -rw-rw-r--  1 openerp openerp 5465 2012-04-17 11:05 Makefile
  26   -rw-rw-r--  1 openerp openerp 2902 2012-04-17 11:05 Makefile_helper.py
  27
  28 If you want some help about the available options, please type::
  29
  30   make help
  31
  32 Next step is to initialize the shared repository and download the sources. Get the current trunk version of OpenERP by typing::
  33
  34   make init-trunk
  35
  36 This will create the following structure inside your ``source`` directory, and fetch the latest source code from ``trunk``::
  37
  38   drwxrwxr-x  3 openerp openerp 4096 2012-04-17 11:10 addons
  39   drwxrwxr-x  3 openerp openerp 4096 2012-04-17 11:10 misc
  40   drwxrwxr-x  3 openerp openerp 4096 2012-04-17 11:10 server
  41   drwxrwxr-x  3 openerp openerp 4096 2012-04-17 11:10 web
  42
  43 Some dependencies are necessary to use OpenERP. Depending on your environment, you might have to install the following packages::
  44
  45   sudo apt-get install graphviz ghostscript postgresql-client
  46
  47   sudo apt-get install python-dateutil python-feedparser python-gdata
  48     python-ldap python-libxslt1 python-lxml python-mako, python-openid
  49     python-psycopg2 python-pybabel python-pychart python-pydot
  50     python-pyparsing python-reportlab python-simplejson python-tz
  51     python-vatnumber python-vobject python-webdav python-werkzeug python-xlwt
  52     python-yaml python-imaging python-matplotlib
  53
  54 Next step is to initialize the database. This will create a new openerp role::
  55
  56   make db-setup
  57
  58 Finally, launch the OpenERP server::
  59
  60   make server
  61
  62 Testing your installation can be done on http://localhost:8069/ . You should see the OpenERP main login page.
  63
  64 .. _Launchpad: https://launchpad.net/
  65 .. _Bazaar: http://bazaar.canonical.com/en/
  66
  67 Command line options
  68 ====================
  69
  70 Using the command ::
  71
  72   ./openerp-server --help
  73
  74 gives you the available command line options. For OpenERP server at revision 4133, an output example is given in the `Command line options example`_. Here are a few interesting command line options.
  75
  76 General Options
  77 +++++++++++++++
  78
  79 ::
  80
  81   --version                           show program version number and exit
  82   -h, --help                          show this help message and exit
  83   -c CONFIG, --config=CONFIG          specify alternate config file
  84   -s, --save                          save configuration to ~/.terp_serverrc
  85   -v, --verbose                       enable debugging
  86   --pidfile=PIDFILE                   file where the server pid will be stored
  87   --logfile=LOGFILE                   file where the server log will be stored
  88   -n INTERFACE, --interface=INTERFACE specify the TCP IP address
  89   -p PORT, --port=PORT                specify the TCP port
  90   --net_interface=NETINTERFACE        specify the TCP IP address for netrpc
  91   --net_port=NETPORT                  specify the TCP port for netrpc
  92   --no-netrpc                         disable netrpc
  93   --no-xmlrpc                         disable xmlrpc
  94   -i INIT, --init=INIT                init a module (use "all" for all modules)
  95   --without-demo=WITHOUT_DEMO         load demo data for a module (use "all" for all modules)
  96   -u UPDATE, --update=UPDATE          update a module (use "all" for all modules)
  97   --stop-after-init                   stop the server after it initializes
  98   --debug                             enable debug mode
  99   -S, --secure                        launch server over https instead of http
 100   --smtp=SMTP_SERVER                  specify the SMTP server for sending mail
 101
 102 Database related options
 103 ++++++++++++++++++++++++
 104
 105 ::
 106
 107   -d DB_NAME, --database=DB_NAME
 108                         specify the database name
 109   -r DB_USER, --db_user=DB_USER
 110                         specify the database user name
 111   -w DB_PASSWORD, --db_password=DB_PASSWORD
 112                         specify the database password
 113   --pg_path=PG_PATH   specify the pg executable path
 114   --db_host=DB_HOST   specify the database host
 115   --db_port=DB_PORT   specify the database port
 116
 117 Internationalization options
 118 ++++++++++++++++++++++++++++
 119
 120 Use these options to translate OpenERP to another language.See i18n section of the user manual. Option '-l' is mandatory.::
 121
 122   -l LANGUAGE, --language=LANGUAGE
 123                        specify the language of the translation file. Use it
 124                        with --i18n-export and --i18n-import
 125   --i18n-export=TRANSLATE_OUT
 126                        export all sentences to be translated to a CSV file
 127                        and exit
 128   --i18n-import=TRANSLATE_IN
 129                        import a CSV file with translations and exit
 130   --modules=TRANSLATE_MODULES
 131                        specify modules to export. Use in combination with
 132                        --i18n-export
 133
 134 Options from previous versions
 135 ++++++++++++++++++++++++++++++
 136
 137 Some options were removed in OpenERP version 6. For example, ``price_accuracy`` is now
 138 configured through the :ref:`decimal_accuracy` screen.
 139
 140 Configuration
 141 ==============
 142
 143 .. _getting_started_configuration-link:
 144
 145 Two configuration files are available:
 146
 147     * one for the client: ``~/.openerprc``
 148     * one for the server: ``~/.openerp_serverrc``
 149
 150 If they are not found, the server and the client will start with a default configuration. Those files follow the convention used by python's ConfigParser module. Please note that lines beginning with "#" or ";" are comments. The client configuration file is automatically generated upon the first start. The sezrver configuration file can automatically be created using the command ::
 151
 152   ./openerp-server -s or ./openerp-server --save
 153
 154 You can specify alternate configuration files with ::
 155
 156   -c CONFIG, --config=CONFIG specify alternate config file
 157
 158 Start-up script
 159 ===============
 160
 161 .. versionadded:: 6.1
 162
 163 To run the OpenERP server, the conventional approach is to use the
 164 `openerp-server` script.  It loads the :ref:`openerp library`, sets a few
 165 configuration variables corresponding to command-line arguments, and starts to
 166 listen to incoming connections from clients.
 167
 168 Depending on your deployment needs, you can write such a start-up script very
 169 easily. We also recommend you take a look at an alternative tool called
 170 `openerp-command` that can, among other things, launch the server.
 171
 172 Yet another alternative is to use a WSGI-compatible HTTP server and let it call
 173 into one of the WSGI entry points of the server.
 174
 175
 176 Appendix
 177 ========
 178
 179 Command line options example
 180 ++++++++++++++++++++++++++++
 181
 182 Usage: openerp-server [options]
 183
 184 **Options**::
 185
 186   --version             show program's version number and exit
 187   -h, --help            show this help message and exit
 188
 189 **Common options**::
 190
 191     -c CONFIG, --config=CONFIG
 192                         specify alternate config file
 193     -s, --save          save configuration to ~/.openerp_serverrc
 194     -i INIT, --init=INIT
 195                         install one or more modules (comma-separated list, use
 196                         "all" for all modules), requires -d
 197     -u UPDATE, --update=UPDATE
 198                         update one or more modules (comma-separated list, use
 199                         "all" for all modules). Requires -d.
 200     --without-demo=WITHOUT_DEMO
 201                         disable loading demo data for modules to be installed
 202                         (comma-separated, use "all" for all modules). Requires
 203                         -d and -i. Default is none
 204     -P IMPORT_PARTIAL, --import-partial=IMPORT_PARTIAL
 205                         Use this for big data importation, if it crashes you
 206                         will be able to continue at the current state. Provide
 207                         a filename to store intermediate importation states.
 208     --pidfile=PIDFILE   file where the server pid will be stored
 209     --addons-path=ADDONS_PATH
 210                         specify additional addons paths (separated by commas).
 211     --load=SERVER_WIDE_MODULES
 212                         Comma-separated list of server-wide modules
 213                         default=web
 214
 215 **XML-RPC Configuration**::
 216
 217     --xmlrpc-interface=XMLRPC_INTERFACE
 218                         Specify the TCP IP address for the XML-RPC protocol.
 219                         The empty string binds to all interfaces.
 220     --xmlrpc-port=XMLRPC_PORT
 221                         specify the TCP port for the XML-RPC protocol
 222     --no-xmlrpc         disable the XML-RPC protocol
 223     --proxy-mode        Enable correct behavior when behind a reverse proxy
 224
 225 **XML-RPC Secure Configuration**::
 226
 227     --xmlrpcs-interface=XMLRPCS_INTERFACE
 228                         Specify the TCP IP address for the XML-RPC Secure
 229                         protocol. The empty string binds to all interfaces.
 230     --xmlrpcs-port=XMLRPCS_PORT
 231                         specify the TCP port for the XML-RPC Secure protocol
 232     --no-xmlrpcs        disable the XML-RPC Secure protocol
 233     --cert-file=SECURE_CERT_FILE
 234                         specify the certificate file for the SSL connection
 235     --pkey-file=SECURE_PKEY_FILE
 236                         specify the private key file for the SSL connection
 237
 238 **NET-RPC Configuration**::
 239
 240     --netrpc-interface=NETRPC_INTERFACE
 241                         specify the TCP IP address for the NETRPC protocol
 242     --netrpc-port=NETRPC_PORT
 243                         specify the TCP port for the NETRPC protocol
 244     --no-netrpc         disable the NETRPC protocol
 245
 246 **Web interface Configuration**::
 247
 248     --db-filter=REGEXP  Filter listed database
 249
 250 **Static HTTP service**::
 251
 252     --static-http-enable
 253                         enable static HTTP service for serving plain HTML
 254                         files
 255     --static-http-document-root=STATIC_HTTP_DOCUMENT_ROOT
 256                         specify the directory containing your static HTML
 257                         files (e.g '/var/www/')
 258     --static-http-url-prefix=STATIC_HTTP_URL_PREFIX
 259                         specify the URL root prefix where you want web
 260                         browsers to access your static HTML files (e.g '/')
 261
 262 **Testing Configuration**::
 263
 264     --test-file=TEST_FILE
 265                         Launch a YML test file.
 266     --test-report-directory=TEST_REPORT_DIRECTORY
 267                         If set, will save sample of all reports in this
 268                         directory.
 269     --test-enable       Enable YAML and unit tests.
 270     --test-commit       Commit database changes performed by YAML or XML
 271                         tests.
 272
 273 **Logging Configuration**::
 274
 275     --logfile=LOGFILE   file where the server log will be stored
 276     --no-logrotate      do not rotate the logfile
 277     --syslog            Send the log to the syslog server
 278     --log-handler=PREFIX:LEVEL
 279                         setup a handler at LEVEL for a given PREFIX. An empty
 280                         PREFIX indicates the root logger. This option can be
 281                         repeated. Example: "openerp.orm:DEBUG" or
 282                         "werkzeug:CRITICAL" (default: ":INFO")
 283     --log-request       shortcut for --log-
 284                         handler=openerp.netsvc.rpc.request:DEBUG
 285     --log-response      shortcut for --log-
 286                         handler=openerp.netsvc.rpc.response:DEBUG
 287     --log-web           shortcut for --log-
 288                         handler=openerp.addons.web.common.http:DEBUG
 289     --log-sql           shortcut for --log-handler=openerp.sql_db:DEBUG
 290     --log-level=LOG_LEVEL
 291                         specify the level of the logging. Accepted values:
 292                         ['info', 'debug_rpc', 'warn', 'test', 'critical',
 293                         'debug_sql', 'error', 'debug', 'debug_rpc_answer',
 294                         'notset'] (deprecated option).
 295
 296 **SMTP Configuration**::
 297
 298     --email-from=EMAIL_FROM
 299                         specify the SMTP email address for sending email
 300     --smtp=SMTP_SERVER  specify the SMTP server for sending email
 301     --smtp-port=SMTP_PORT
 302                         specify the SMTP port
 303     --smtp-ssl          specify the SMTP server support SSL or not
 304     --smtp-user=SMTP_USER
 305                         specify the SMTP username for sending email
 306     --smtp-password=SMTP_PASSWORD
 307                         specify the SMTP password for sending email
 308
 309 **Database related options**::
 310
 311     -d DB_NAME, --database=DB_NAME
 312                         specify the database name
 313     -r DB_USER, --db_user=DB_USER
 314                         specify the database user name
 315     -w DB_PASSWORD, --db_password=DB_PASSWORD
 316                         specify the database password
 317     --pg_path=PG_PATH   specify the pg executable path
 318     --db_host=DB_HOST   specify the database host
 319     --db_port=DB_PORT   specify the database port
 320     --db_maxconn=DB_MAXCONN
 321                         specify the the maximum number of physical connections
 322                         to posgresql
 323     --db-template=DB_TEMPLATE
 324                         specify a custom database template to create a new
 325                         database
 326
 327 **Internationalisation options**::
 328
 329     Use these options to translate OpenERP to another language.See i18n
 330     section of the user manual. Option '-d' is mandatory.Option '-l' is
 331     mandatory in case of importation
 332
 333     --load-language=LOAD_LANGUAGE
 334                         specifies the languages for the translations you want
 335                         to be loaded
 336     -l LANGUAGE, --language=LANGUAGE
 337                         specify the language of the translation file. Use it
 338                         with --i18n-export or --i18n-import
 339     --i18n-export=TRANSLATE_OUT
 340                         export all sentences to be translated to a CSV file, a
 341                         PO file or a TGZ archive and exit
 342     --i18n-import=TRANSLATE_IN
 343                         import a CSV or a PO file with translations and exit.
 344                         The '-l' option is required.
 345     --i18n-overwrite    overwrites existing translation terms on updating a
 346                         module or importing a CSV or a PO file.
 347     --modules=TRANSLATE_MODULES
 348                         specify modules to export. Use in combination with
 349                         --i18n-export
 350
 351 **Security-related options**::
 352
 353     --no-database-list  disable the ability to return the list of databases
 354
 355 **Advanced options**::
 356
 357     --cache-timeout=CACHE_TIMEOUT
 358                         set the timeout for the cache system
 359     --debug             enable debug mode
 360     --stop-after-init   stop the server after its initialization
 361     -t TIMEZONE, --timezone=TIMEZONE
 362                         specify reference timezone for the server (e.g.
 363                         Europe/Brussels
 364     --osv-memory-count-limit=OSV_MEMORY_COUNT_LIMIT
 365                         Force a limit on the maximum number of records kept in
 366                         the virtual osv_memory tables. The default is False,
 367                         which means no count-based limit.
 368     --osv-memory-age-limit=OSV_MEMORY_AGE_LIMIT
 369                         Force a limit on the maximum age of records kept in
 370                         the virtual osv_memory tables. This is a decimal value
 371                         expressed in hours, and the default is 1 hour.
 372     --max-cron-threads=MAX_CRON_THREADS
 373                         Maximum number of threads processing concurrently cron
 374                         jobs.
 375     --virtual-memory-limit=VIRTUAL_MEMORY_LIMIT
 376                         Maximum allowed virtual memory per Gunicorn process.
 377                         When the limit is reached, any memory allocation will
 378                         fail.
 379     --virtual-memory-reset=VIRTUAL_MEMORY_RESET
 380                         Maximum allowed virtual memory per Gunicorn process.
 381                         When the limit is reached, the worker will be reset
 382                         after the current request.
 383     --cpu-time-limit=CPU_TIME_LIMIT
 384                         Maximum allowed CPU time per Gunicorn process. When
 385                         the limit is reached, an exception is raised.
 386     --unaccent          Use the unaccent function provided by the database
 387                         when available.
 388
 389 Server configuration file
 390 +++++++++++++++++++++++++
 391
 392 ::
 393
 394   [options]
 395   addons_path = /home/openerp/workspace/openerp-dev/addons/trunk,/home/openerp/workspace/openerp-dev/web/trunk/addons
 396   admin_passwd = admin
 397   cache_timeout = 100000
 398   cpu_time_limit = 60
 399   csv_internal_sep = ,
 400   db_host = False
 401   db_maxconn = 64
 402   db_name = False
 403   db_password = False
 404   db_port = False
 405   db_template = template0
 406   db_user = openerp
 407   dbfilter = .*
 408   debug_mode = False
 409   demo = {}
 410   email_from = False
 411   import_partial =
 412   list_db = True
 413   log_handler = [':INFO']
 414   log_level = info
 415   logfile = False
 416   login_message = False
 417   logrotate = True
 418   max_cron_threads = 4
 419   netrpc = True
 420   netrpc_interface =
 421   netrpc_port = 8070
 422   osv_memory_age_limit = 1.0
 423   osv_memory_count_limit = False
 424   pg_path = None
 425   pidfile = False
 426   proxy_mode = False
 427   reportgz = False
 428   secure_cert_file = server.cert
 429   secure_pkey_file = server.pkey
 430   server_wide_modules = None
 431   smtp_password = False
 432   smtp_port = 25
 433   smtp_server = localhost
 434   smtp_ssl = False
 435   smtp_user = False
 436   static_http_document_root = None
 437   static_http_enable = False
 438   static_http_url_prefix = None
 439   syslog = False
 440   test_commit = False
 441   test_enable = False
 442   test_file = False
 443   test_report_directory = False
 444   timezone = False
 445   translate_modules = ['all']
 446   unaccent = False
 447   virtual_memory_limit = 805306368
 448   virtual_memory_reset = 671088640
 449   without_demo = False
 450   xmlrpc = True
 451   xmlrpc_interface =
 452   xmlrpc_port = 8069
 453   xmlrpcs = True
 454   xmlrpcs_interface =
 455   xmlrpcs_port = 8071