8000 [ADD] odoo_sh: documentation · senmax/documentation-user@1466403 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1466403

Browse files
beledouxdenisbeledouxdenis
committed
[ADD] odoo_sh: documentation
1 parent b7cfc92 commit 1466403

File tree

63 files changed

+1650
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+1650
-0
lines changed

‎_static/banners/odoo-sh.jpg

256 KB
Loading

‎odoo_sh/advanced.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
:banner: banners/odoo-sh.jpg
2+
3+
=================
4+
Advanced
5+
=================
6+
7+
.. toctree::
8+
:titlesonly:
9+
10+
advanced/containers
11+
advanced/submodules

‎odoo_sh/advanced/containers.rst

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
:banner: banners/odoo-sh.jpg
2+
3+
==================================
4+
Containers
5+
==================================
6+
7+
Overview
8+
========
9+
10+
Each build is isolated within its own container (Linux namespaced container).
11+
12+
The base is an Ubuntu 16.04 system, where all of Odoo's required dependencies,
13+
as well as common useful packages, are installed.
14+
15+
The Odoo.sh team is open to install any system packages
16+
as long as they are distributed in the official Ubuntu repositories.
17+
`Leave us a feedback <https://www.odoo.sh/feedback>`_ if you would like a package not yet installed.
18+
19+
If your project requires additional Python dependencies, or more recent releases,
20+
you can define a :file:`requirements.txt` file in the root of your branches listing them.
21+
The platform will take care to install these dependencies in your containers.
22+
`The pip requirements specifiers <https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_
23+
documentation can help you write a :file:`requirements.txt` file.
24+
To have a concrete example,
25+
check out the `requirements.txt file of Odoo <https://github.com/odoo/odoo/blob/11.0/requirements.txt>`_.
26+
27+
The :file:`requirements.txt` files of submodules are taken into account as well. The platform
28+
looks for :file:`requirements.txt` files in each folder containing Odoo modules: Not in the module folder itself,
29+
but in their parent folder.
30+
31+
Directory structure
32+
===================
33+
34+
As the containers are Ubuntu based, their directory structure follows the linux Filesystem Hierarchy Standard.
35+
`Ubuntu's filesystem tree overview <https://help.ubuntu.com/community/LinuxFilesystemTreeOverview#Main_directories>`_
36+
explains the main directories.
37+
38+
Here are the Odoo.sh pertinent directories:
39+
40+
::
41+
42+
.
43+
├── home
44+
│ └── odoo
45+
│ ├── src
46+
│ │ ├── odoo Odoo Community source code
47+
│ │ │ └── odoo-bin Odoo server executable
48+
│ │ ├── enterprise Odoo Enterprise source code
49+
│ │ ├── themes Odoo Themes source code
50+
│ │ └── user Your repository branch source code
51+
│ ├── data
52+
│ │ ├── filestore database attachments, as well as the files of binary fields
53+
│ │ └── sessions visitors and users sessions
54+
│ └── logs
55+
│ ├── install.log Database installation logs
56+
│ ├── odoo.log Running server logs
57+
│ ├── update.log Database updates logs
58+
│ └── pip.log Python packages installation logs
59+
└── usr
60+
├── lib
61+
│ ├── python2.7
62+
│ └── dist-packages Python 2.7 standard libraries
63+
│ ├── python3
64+
│ └── dist-packages Python 3 standard libraries
65+
│ └── python3.5
66+
│ └── dist-packages Python 3.5 standard libraries
67+
├── local
68+
│ └── lib
69+
│ ├── python2.7
70+
│ │ └── dist-packages Python 2.7 third-party libraries
71+
│ └── python3.5
72+
│ └── dist-packages Python 3.5 third-party libraries
73+
└── usr
74+
└── bin
75+
├── python2.7 Python 2.7 executable
76+
└── python3.5 Python 3.5 executable
77+
78+
Both Python 2.7 and 3.5 are installed in the containers. However:
79+
80+
* If your project is configured to use Odoo 10.0, the Odoo server runs with Python 2.7.
81+
* If your project is configured to use Odoo 11.0, the Odoo server runs with Python 3.5.
82+
83+
Database shell
84+
==============
85+
86+
While accessing a container with the shell, you can access the database using *psql*.
87+
88+
.. code-block:: bash
89+
90+
odoo@odoo-addons-master-1.odoo.sh:~$ psql
91+
psql (9.5.2, server 9.5.11)
92+
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, bits: 256, compression: off)
93+
Type "help" for help.
94+
95+
odoo-addons-master-1=>
96+
97+
**Be careful !**
98+
`Use transactions <https://www.postgresql.org/docs/current/static/sql-begin.html>`_ (*BEGIN...COMMIT/ROLLBACK*)
99+
for every *sql* statements leading to changes
100+
(*UPDATE*, *DELETE*, *ALTER*, ...), especially for your production database.
101+
102+
The transaction mechanism is your safety net in case of mistake.
103+
You simply have to rollback your changes to revert your database to its previous state.
104+
105+
For example, it may happen that you forget to set your *WHERE* condition.
106+
107+
.. code-block:: sql
108+
109+
odoo-addons-master-1=> BEGIN;
110+
BEGIN
111+
odoo-addons-master-1=> UPDATE res_users SET password = '***';
112+
UPDATE 457
113+
odoo-addons-master-1=> ROLLBACK;
114+
ROLLBACK
115+
116+
In such a case, you can rollback to revert the unwanted changes that you just mistakenly did, and rewrite the statement:
117+
118+
.. code-block:: sql
119+
120+
odoo-addons-master-1=> BEGIN;
121+
BEGIN
122+
odoo-addons-master-1=> UPDATE res_users SET password = '***' WHERE id = 1;
123+
UPDATE 1
124+
odoo-addons-master-1=> COMMIT;
125+
COMMIT
126+
127+
However, do not forget to either commit or rollback your transaction after having done it.
128+
Open transactions may lock records in your tables
129+
and your running database may wait for them to be released. It can cause a server to hang indefinitely.
130+
131+
In addition, when possible, use your staging databases to test your statements first. It gives you an extra safety net.
132+
133+
Run an Odoo server
134+
==================
135+
136+
You can start an Odoo server instance from a container shell. You won't be able to access it from the outside world
137+
with a browser, but you can for instance:
138+
139+
* use the Odoo shell,
140+
141+
.. code-block:: bash
142+
143+
$ ~/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
144+
>>> partner = env['res.partner'].search([('email', '=', 'asusteK@yourcompany.example.com')], limit=1)
145+
>>> partner.name
146+
'ASUSTeK'
147+
>>> partner.name = 'Odoo'
148+
>>> env['res.partner'].search([('email', '=', 'asusteK@yourcompany.example.com')], limit=1).name
149+
'Odoo'
150+
151+
* install a module,
152+
153+
.. code-block:: bash
154+
155+
$ ~/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
156+
157+
* update a module,
158+
159+
.. code-block:: bash
160+
161+
$ ~/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
162+
163+
* run the tests for a module,
164+
165+
.. code-block:: bash
166+
167+
$ ~/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
168+
169+
In the above commands, the argument:
170+
171+
* *--addons-path* is to specify the directories containing the modules,
172+
the part *~/src/user* can vary, according to your branch code structure,
173+
* *--workers=0* is to run your server using multi-threading instead of multiple workers,
174+
* *--max-cron-threads=0* is to prevent the scheduled tasks to run,
175+
* *--stop-after-init* is to immediately shutdown the server instance after it completed the operations you asked.
176+
177+
More options are available and detailed in the
178+
`CLI documentation <https://www.odoo.com/documentation/11.0/reference/cmdline.html>`_.
179+
180+
You can find in the logs (*~/logs/odoo.log*) the addons path used by Odoo.sh to run your server.
181+
Look for "*odoo: addons paths*":
182+
183+
::
184+
185+
2018-02-19 10:51:39,267 4 INFO ? odoo: Odoo version 11.0
186+
2018-02-19 10:51:39,268 4 INFO ? odoo: Using configuration file at /home/odoo/.config/odoo/odoo.conf
187+
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']
188+
189+
**Be careful**, especially with your production database.
190+
Operations that you perform running this Odoo server instance are not isolated:
191+
Changes will be effective in the database. Always, make your tests in your staging databases.

‎odoo_sh/advanced/media/advanced-submodules-button.png

6.07 KB
Loading

‎odoo_sh/advanced/media/advanced-submodules-dialog.png

12.9 KB
Loading

‎odoo_sh/advanced/media/advanced-submodules-github-sshurl.png

8.37 KB
Loading

‎odoo_sh/advanced/submodules.rst

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
:banner: banners/odoo-sh.jpg
2+
3+
.. _odoosh-advanced-submodules:
4+
5+
==================================
6+
Submodules
7+
==================================
8+
9+
Overview
10+
========
11+
12+
A `Git submodule <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allows you to integrate other Git projects
13+
into your code, without the need to copy-paste all their code.
14+
15+
Indeed, your custom modules can depend on modules from other repositories.
16+
Regarding Odoo, this feature allows you to add modules from other Git repositories into the branches of your repository.
17+
Adding these dependencies in your branch through submodules makes the deployment of your code and servers easier,
18+
as you can clone the repositories added as submodules at the same time you clone your own repository.
19+
20+
Besides, you can choose the branch of the repository added as submodule
21+
and you have the control of the revision you want.
22+
It's up to you to decide wether you want to pin the submodule to a specific revision and when you want to update
23+
to a newer revision.
24+
25+
In Odoo.sh, the submodules gives you the possibility to use and depends on modules available in other repositories.
26+
The platform will detect that you added modules through submodules in your branches
27+
and add them to your addons path automatically so you can install them in your databases.
28+
29+
If you add private repositories as submodules in your branches,
30+
you need to configure a deploy key in your Odoo.sh project settings and in your repository settings.
31+
Otherwise Odoo.sh won't be allowed to download them.
32+
The procedure is detailed in the chapter :ref:`Settings > Submodules <odoosh-gettingstarted-settings-submodules>`.
33+
34+
Adding a submodule
35+
==================
36+
37+
With Odoo.sh (simple)
38+
---------------------
39+
40+
On Odoo.sh, in the branches view of your project, choose the branch in which you want to add a submodule.
41+
42+
In the upper right corner, click on the *Submodule* button, and then on *Run*.
43+
44+
.. image:: ./media/advanced-submodules-button.png
45+
:align: center
46+
47+
A dialog with a form is shown. Fill the inputs as follows:
48+
49+
* Repository URL: The SSH URL of the repository.
50+
* Branch: The branch you want to use.
51+
* Path: The folder in which you want to add this submodule in your branch.
52+
53+
.. image:: ./media/advanced-submodules-dialog.png
54+
:align: center
55+
56+
On Github, you can get the repository URL with the *Clone or download* button of the repository. Make sure to *use SSH*.
57+
58+
.. image:: ./media/advanced-submodules-github-sshurl.png
59+
:align: center
60+
61+
For now it is not possible to add **private** repositories with this method.
62+
You can nevertheless do so :ref:`with Git <odoosh-advanced-submodules-withgit>`.
63+
64+
.. _odoosh-advanced-submodules-withgit:
65+
66+
With Git (advanced)
67+
---------------------
68+
69+
In a terminal, in the folder where your Git repository is cloned,
70+
checkout the branch in which you want to add a submodule:
71+
72+
.. code-block:: bash
73+
74+
$ git checkout <branch>
75+
76+
Then, add the submodule using the command below:
77+
78+
.. code-block:: bash
79+
80+
$ git submodule add -b <branch> <git@yourprovider.com>:<username/repository.git> <path>
81+
82+
Replace
83+
84+
* *<git@yourprovider.com>:<username/repository.git>* by the SSH URL of the repository you want to add as submodule,
85+
* *<branch>* by the branch you want to use in the above repository,
86+
* *<path>* by the folder in which you want to add this submodule.
87+
88+
Commit and push your changes:
89+
90+
.. code-block:: bash
91+
92+
$ git commit -a && git push -u <remote> <branch>
93+
94+
Replace
95+
96+
* <remote> by the repository on which you want to push your changes. For a standard Git setup, this is *origin*.
97+
* <branch> by the branch on which you want to push your changes.
98+
Most likely the branch you used :code:`git checkout` on in the first step.
99+
100+
You can read the `git-scm.com documentation <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_
101+
for more details about the Git submodules.
102+
For instance, if you would like to update your submodules to have their latest revision,
103+
you can follow the chapter
104+
`Pulling in Upstream changes <https://git-scm.com/book/en/v2/Git-Tools-Submodules#_pulling_in_upstream_changes>`_.

‎odoo_sh/documentation.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
:banner: banners/odoo-sh.jpg
2+
3+
==========================
4+
Odoo.sh
5+
==========================
6+
7+
.. toctree::
8+
:titlesonly:
9+
10+
overview
11+
getting_started
12+
advanced

‎odoo_sh/getting_started.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:banner: banners/odoo-sh.jpg
2+
3+
=================
4+
Get started
5+
=================
6+
7+
.. toctree::
8+
:titlesonly:
9+
10+
getting_started/create
11+
getting_started/branches
12+
getting_started/builds
13+
getting_started/status
14+
getting_started/settings
15+
getting_started/first_module

0 commit comments

Comments
 (0)
0