diff --git a/odoo_sh/advanced/containers.rst b/odoo_sh/advanced/containers.rst index c53dead48..e0dc4457a 100644 --- a/odoo_sh/advanced/containers.rst +++ b/odoo_sh/advanced/containers.rst @@ -20,10 +20,14 @@ If your project requires Python dependencies not installed by default in the con you can define a *requirements.txt* file, listing your Python modules dependencies, in the root of your branches. The platform will take care to install these dependencies in your containers. `The pip requirements specifiers `_ -documentation can help you to know how to write a `requirements.txt` file. +documentation can help you to know how to write a *requirements.txt* file. To have a concrete example, check out the `requirements.txt file of Odoo `_. +The *requirements.txt* files of submodules are taken into account as well. The platform +looks for *requirements.txt* files in each folders containing Odoo modules: Not in the module folder itself, +but in their parent folder. + Directory structure =================== @@ -37,17 +41,147 @@ The Odoo.sh pertinent directories are presented in the below list: . ├── home - └── odoo - ├── src - │ ├── odoo Odoo Community source code - │ ├── enterprise Odoo Enterprise source code - │ ├── themes Odoo Themes source code - │ └── user source code of your repository branch associated to the build - ├── data - │ ├── filestore the database attachments, as well as the files of binary fields - │ └── sessions the visitors and users sessions - └── logs - ├── install.log Database installation logs - ├── odoo.log Running server logs - └── update.log Database updates logs - └── pip.log Python packages installation logs + │ └── odoo + │ ├── src + │ │ ├── odoo Odoo Community source code + │ │ │ └── odoo-bin Odoo server executable + │ │ ├── enterprise Odoo Enterprise source code + │ │ ├── themes Odoo Themes source code + │ │ └── user Your repository branch source code + │ ├── data + │ │ ├── filestore database attachments, as well as the files of binary fields + │ │ └── sessions visitors and users sessions + │ └── logs + │ ├── install.log Database installation logs + │ ├── odoo.log Running server logs + │ ├── update.log Database updates logs + │ └── pip.log Python packages installation logs + └── usr + ├── lib + │ ├── python2.7 + │ └── dist-packages Python 2.7 standard libraries + │ ├── python3 + │ └── dist-packages Python 3 standard libraries + │ └── python3.5 + │ └── dist-packages Python 3.5 standard libraries + ├── local + │ └── lib + │ ├── python2.7 + │ │ └── dist-packages Python 2.7 third-party libraries + │ └── python3.5 + │ └── dist-packages Python 3.5 third-party libraries + └── usr + └── bin + ├── python2.7 Python 2.7 executable + └── python3.5 Python 3.5 executable + +Both Python 2.7 and 3.5 are installed in the containers. However: + +* If your project is configured to use Odoo 10.0, the Odoo server runs with Python 2.7. +* If your project is configured to use Odoo 11.0, the Odoo server runs with Python 3.5. + +Database shell +============== + +While accessing a container with the shell, you can access the database using *psql*. + +.. code-block:: bash + + odoo@odoo-addons-master-1.odoo.sh:~$ psql + psql (9.5.2, server 9.5.11) + SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off) + Type "help" for help. + + odoo-addons-master-1=> + +**Be careful !** +Use transactions (*BEGIN...COMMIT/ROLLBACK*) for every *sql* requests leading to changes +(*UPDATE*, *DELETE*, *ALTER*, ...), especially for your production database. + +It happens to be distracted, and the transaction mechanism may save you. +Indeed, it gives you the opportunity to rollback your changes in case you make a mistake. + +For example, it may happen that you forget to set your *WHERE* condition. + +.. code-block:: sql + + odoo-addons-master-1=> BEGIN; + BEGIN + odoo-addons-master-1=> UPDATE res_users SET password = '***'; + UPDATE 457 + odoo-addons-master-1=> ROLLBACK; + ROLLBACK + +In such a case, you can rollback to revert the unwanted changes that you just mistakenly did, and rewrite the request: + +.. code-block:: sql + + odoo-addons-master-1=> BEGIN; + BEGIN + odoo-addons-master-1=> UPDATE res_users SET password = '***' WHERE id = 1; + UPDATE 1 + odoo-addons-master-1=> COMMIT; + COMMIT + +However, do not forget to either commit or rollback your request after having done it. +An opened transaction may have locked records in your tables, +and your running database may wait for them to be released. It can cause a server to hang up indefinitely. + +In addition, when possible, use your staging databases to test your requests first. It gives you an extra safety ney. + +Run an Odoo server +================== + +You can start an Odoo server instance from a container shell. You won't be able to access it from the outside world +with a browser, but you can for instance: + +* use the Odoo shell, + +.. code-block:: bash + + $ ~/src/odoo/odoo-bin shell -d odoo-addons-master-1 --addons-path=~/src/user,~/src/enterprise,~/src/themes,~/src/odoo/addons,~/src/odoo/odoo/addons --workers=0 --max-cron-threads=0 + >>> partner = env['res.partner'].search([('email', '=', 'asusteK@yourcompany.example.com')], limit=1) + >>> partner.name + 'ASUSTeK' + >>> partner.name = 'Odoo' + >>> env['res.partner'].search([('email', '=', 'asusteK@yourcompany.example.com')], limit=1).name + 'Odoo' + +* install a module, + +.. code-block:: bash + + $ ~/src/odoo/odoo-bin -d odoo-addons-master-1 --addons-path=~/src/user,~/src/enterprise,~/src/themes,~/src/odoo/addons,~/src/odoo/odoo/addons -i sale --workers=0 --max-cron-threads=0 --stop-after-init + +* update a module, + +.. code-block:: bash + + $ ~/src/odoo/odoo-bin -d odoo-addons-master-1 --addons-path=~/src/user,~/src/enterprise,~/src/themes,~/src/odoo/addons,~/src/odoo/odoo/addons -u sale --workers=0 --max-cron-threads=0 --stop-after-init + +* run the tests for a module, + +.. code-block:: bash + + $ ~/src/odoo/odoo-bin -d odoo-addons-master-1 --addons-path=~/src/user,~/src/enterprise,~/src/themes,~/src/odoo/addons,~/src/odoo/odoo/addons -i sale --test-enable --log-level=test --workers=0 --max-cron-threads=0 --stop-after-init + +In the above commands, the argument: + +* *--addons-path* is to specify the directories containing the modules, + the part *~/src/user* can vary, according to your branch code structure, +* *--workers=0* is to run your server using multi-threading instead of multiple workers, +* *--max-cron-threads=0* is to prevent the scheduled tasks to run. +* *--stop-after-init* is to immediately shutdown the server instance after it completed the operations you asked. + +You can find in the logs (*~/logs/odoo.log*) the addons path used by Odoo.sh to run your server. +Look for "*odoo: addons paths*": + +:: + + 2018-02-19 10:51:39,267 4 INFO ? odoo: Odoo version 11.0 + 2018-02-19 10:51:39,268 4 INFO ? odoo: Using configuration file at /home/odoo/.config/odoo/odoo.conf + 2018-02-19 10:51:39,268 4 INFO ? odoo: addons paths: ['/home/odoo/data/addons/11.0', '/home/odoo/src/user', '/home/odoo/src/enterprise', '/home/odoo/src/themes', '/home/odoo/src/odoo/addons', '/home/odoo/src/odoo/odoo/addons'] + +**Be careful**, especially with your production database. +Operations that you perform running this Odoo server instance are not isolated: +Changes will be effective in the database. As much as possible, make your tests in your staging databases. diff --git a/odoo_sh/getting_started.rst b/odoo_sh/getting_started.rst index a88cfe652..8193c6a88 100644 --- a/odoo_sh/getting_started.rst +++ b/odoo_sh/getting_started.rst @@ -12,3 +12,4 @@ Get started getting_started/builds getting_started/status getting_started/settings + getting_started/first_module diff --git a/odoo_sh/getting_started/first_module.rst b/odoo_sh/getting_started/first_module.rst new file mode 100644 index 000000000..afd1fa9fe --- /dev/null +++ b/odoo_sh/getting_started/first_module.rst @@ -0,0 +1,115 @@ +:banner: banners/odoo-sh.jpg + +================================== +Your first module +================================== + +Overview +======== + +This chapter helps you to create your first Odoo module and deploy it on Odoo.sh. +Basic use of git and Github is explained. + +In this tutorial, *~/src* is assumed the directory where are located the Git repositories related to your Odoo projects. +Feel free to replace it by the directory of your choice. + +Create the development branch +============================= + +Clone your Github repository on your computer: + +.. code-block:: bash + + $ mkdir ~/src; cd ~/src + $ git clone https://github.com//.git + +Replace: + +* with your Github user or organization name, +* with repository name. + +Create a new branch: + +.. code-block:: bash + + $ git checkout -b feature-1 master + +Replace: +* *feature-1* by the name of your choice, +* *master* by the name of your production branch. If you just created your project, and do not have a production branch, +you can leave *master*. + + +Create the module structure +=========================== + +Scaffolding the module +---------------------- + +While not necessary, scaffolding avoids the tedium of setting the basic Odoo module structure. +It nevertheless requires *odoo-bin*, and therefore the +`installation of Odoo `_ on your computer. + +Use *odoo-bin scaffold* to generate the module structure in your repository: + +.. code-block:: bash + + $ ./odoo-bin scaffold my_module ~/src// + +Replace: + +* with your repository name. + +This will generate the below structure: + +:: + + my_module + ├── __init__.py + ├── __manifest__.py + ├── controllers + │   ├── __init__.py + │   └── controllers.py + ├── demo + │   └── demo.xml + ├── models + │   ├── __init__.py + │   └── models.py + ├── security + │   └── ir.model.access.csv + └── views + ├── templates.xml + └── views.xml + +.. Warning:: + + Do not use special characters other than the underscore ( _ ) for your module name, not even an hyphen ( - ). + This name is used for the Python classes of your module, + and having classes name with special characters other than the underscore is not valid in Python. + +Uncomment the content of the files: + +* models/models.py, + an example of model with its fields, +* views/views.xml, + a tree and a form view, with the menus opening them, +* demo/demo.xml, + Demo records for the above example model. +* controllers/controllers.py, + an example of controller implementing some routes, +* views/templates.xml, + two example qweb views used by the above controller routes, + +Manually +-------- + +If you want to create your module structure manually, +you can follow `Build an Odoo module `_ to understand +the structure of a module and the content of each file. + +Push the development branch +=========================== + +.. code-block:: bash + + $ git push -u origin feature-1