m

odoo_sh/advanced/containers.rst

@@ -1,6 +1,53 @@
+:banner: banners/odoo-sh.jpg
+
 ==================================
 Containers
 ==================================
 
 Overview
 ========
+
+Each build is isolated within its own container (Linux namespaced container).
+
+The base is an Ubuntu 16.04 system, where are installed all required Odoo dependencies
+as well as common useful packages.
+
+The Odoo.sh team is open to install any system packages
+as long as they are distributed by the official Ubuntu repositories.
+`Leave us a feedback <https://www.odoo.sh/feedback>`_ if you would like a package which is not yet installed.
+
+If your project requires Python dependencies not installed by default in the container, or more recent releases,
+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 <https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_
+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 <https://github.com/odoo/odoo/blob/11.0/requirements.txt>`_.
+
+Directory structure
+===================
+
+As the containers are Ubuntu based, their directory structure follows the linux Filesystem Hierarchy Standard.
+`Ubuntu's filesystem tree overview <https://help.ubuntu.com/community/LinuxFilesystemTreeOverview#Main_directories>`_
+explains the main directories.
+
+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_sh/advanced/submodules.rst

@@ -1,6 +1,100 @@
+:banner: banners/odoo-sh.jpg
+
 ==================================
 Submodules
 ==================================
 
 Overview
 ========
+
+A `Git submodule <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allows you to integrate other Git projects
+into your code, without the need to copy-paste all their code.
+
+Indeed, your custom modules can depend on modules from other repositories.
+Regarding Odoo, this feature allows you to add modules from other Git repositories into the branches of your repository.
+Adding these dependencies within your branch through submodules makes easier the deployment of your code and servers,
+as you can clone the repositories added as submodules in the same time you clone your own repository.
+
+Besides, you can choose the branch of the repository added as submodule
+and you have the control of the revision you want.
+It's up to you to decide wether you want to pin the submodule to a specific revision and when you want to update
+to a newer revision.
+
+In Odoo.sh, the submodules gives you the possibility to use and depends on modules available in other repositories.
+The platform will detect automatically that you added modules through submodules within your branches,
+and add them within your addons path so you can install them in your databases.
+
+If you add private repositories as submodules in your branches,
+you need to configure a deploy key in your Odoo.sh project settings and in your repository settings.
+Otherwise Odoo.sh won't be allowed to download them.
+The procedure is detailed in the chapter `Settings <../getting_started/settings.html#submodules>`_ of this documentation.
+
+Adding a submodule
+==================
+
+With Odoo.sh (simple)
+---------------------
+
+On Odoo.sh, in the branches view of your project, choose the branch in which you want to add a submodule.
+
+In the upper right corner, click on the *Submodule* button, and then on *Run*.
+
+.. image:: ./media/advanced-submodules-button.png
+   :align: center
+
+A dialog with a form is shown. Fill the inputs as follow:
+
+* Repository URL: The SSH URL of the repository.
+* Branch: The branch you want to use.
+* Path: The folder in which you want to add this submodule in your branch.
+
+.. image:: ./media/advanced-submodules-dialog.png
+   :align: center
+
+On Github, you can get the repository URL with the *Clone or download* button of the repository. Make sure to *use SSH*.
+
+.. image:: ./media/advanced-submodules-github-sshurl.png
+  :align: center
+
+At the moment, this is not possible to use this method to add private repositories.
+You can nevertheless do so `with git <#with-git-advanced>`_.
+
+With Git (advanced)
+---------------------
+
+In a terminal, in the folder where is cloned your Git repository,
+checkout the branch in which you want to add a submodule:
+
+.. code-block:: bash
+
+  $ git checkout <branch>
+
+Then, add the submodule using the below command:
+
+.. code-block:: bash
+
+  $ git submodule add -b <branch> <git@yourprovider.com:<username/repository.git> <path>
+
+Replace
+
+* *<git@yourprovider.com:<username/repository.git>* by the SSH URL of the repository you want to add as submodule,
+* *<branch>* by the branch you want to use in the above repository,
+* *<path>* by the folder in which you want to add this submodule.
+
+Commit and push your changes:
+
+.. code-block:: bash
+
+  $ git commit -a && git push -u <remote> <branch>
+
+Replace
+
+* <remote> by the repository on which you want to push your changes. For a standard git setup, this is *origin*.
+* <branch> by the branch on which you want to push your changes.
+  Most-likely the branch you checkouted in the above steps.
+
+You can read the `git-scm.com documentation <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_
+for more details about the Git submodules.
+For instance, if you would like to update your submodules to have their latest revision,
+you can follow the chapter
+`Pulling in Upstream changes <https://git-scm.com/book/en/v2/Git-Tools-Submodules#_pulling_in_upstream_changes>`_.

odoo_sh/getting_started/branches.rst

@@ -270,8 +270,9 @@ Submodule
 Add a branch from another repository in your current branch as a *submodule*.
 
 *Submodules* allows you to use modules from other repositories in your project.
-The `git-scm documentation about submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ can help you to know
-more about *submodules*.
+
+The submodules feature is detailed in the chapter
+`Submodules <../advanced/submodules.html>`_ of this documentation.
 
 .. code-block:: bash
 
@@ -291,10 +292,6 @@ Commits all your current changes.
 
 Uploads the changes you just added in the *master* branch on your remote repository.
 
-If you add private repositories as submodules in your branches,
-you need to configure a deploy key in your Odoo.sh project settings and in your repository settings.
-Otherwise Odoo.sh won't be allowed to download them.
-
 Delete
 ------
 

odoo_sh/getting_started/settings.rst

@@ -148,10 +148,11 @@ HTTPS/SSL
 ---------
 
 You can use a third-party CDN such as *Cloudflare.com* to enable the *HTTPS* support for your custom domain:
-  * `Create a Cloudflare account <https://support.cloudflare.com/hc/en-us/articles/201720164-Step-2-Create-a-Cloudflare-account-and-add-a-website>`_
-  * `Change your domain name servers to Cloudflare <https://support.cloudflare.com/hc/en-us/articles/205195708-Step-3-Change-your-domain-name-servers-to-Cloudflare>`_
-  * `Choose an SSL mode <https://support.cloudflare.com/hc/en-us/articles/201897700-Step-4-Recommended-First-Steps-for-all-Cloudflare-users#sslmode>`_
-  * `Redirect your visitors to HTTPS <https://support.cloudflare.com/hc/en-us/articles/200170536-How-do-I-redirect-all-visitors-to-HTTPS-SSL->`_
+
+* `Create a Cloudflare account <https://support.cloudflare.com/hc/en-us/articles/201720164-Step-2-Create-a-Cloudflare-account-and-add-a-website>`_
+* `Change your domain name servers to Cloudflare <https://support.cloudflare.com/hc/en-us/articles/205195708-Step-3-Change-your-domain-name-servers-to-Cloudflare>`_
+* `Choose an SSL mode <https://support.cloudflare.com/hc/en-us/articles/201897700-Step-4-Recommended-First-Steps-for-all-Cloudflare-users#sslmode>`_
+* `Redirect your visitors to HTTPS <https://support.cloudflare.com/hc/en-us/articles/200170536-How-do-I-redirect-all-visitors-to-HTTPS-SSL->`_
 
 Submodules
 ==========
@@ -162,7 +163,7 @@ as submodules in your branches to allow Odoo.sh to download them.
 .. Warning::
   These settings are required for **private repositories** only.
   If you are looking on how to set up your submodules,
-  instructions are available in the `Advanced/Submodules <../advanced/submodules.html>`_ chapter of this documentation.
+  instructions are available in the chapter `Submodules <../advanced/submodules.html>`_ of this documentation.
 
 .. image:: ./media/interface-settings-submodules.png
    :align: center