From 0f2b82cb37c51674876a791491d6be7eaa6c97a6 Mon Sep 17 00:00:00 2001 From: Julien Castiaux Date: Tue, 24 May 2022 14:50:14 +0000 Subject: [PATCH] [IMP] install/deploy: serve static file/attachment Odoo is compatible with X-Sendfile (apache) and X-Accel (nginx). They are web server extension that can be used by the web application (Odoo) to delegate serving local files to the web server (apache/nginx). We use those extension to stream attachments. The documentation now explains what is X-Sendfile/X-Accel and how to configure each web server. Along those changes, the few sentences about serving static files have been reworded and now include various configuration examples. closes odoo/documentation#2083 Task: 2801675 Related: odoo/odoo#88134 Related: odoo/enterprise#26191 Signed-off-by: Antoine Vandevenne (anv) --- content/administration/install/deploy.rst | 114 +++++++++++++++++++--- content/developer/misc/other/cmdline.rst | 6 ++ 2 files changed, 109 insertions(+), 11 deletions(-) diff --git a/content/administration/install/deploy.rst b/content/administration/install/deploy.rst index 31e8b24d1..d83959e36 100644 --- a/content/administration/install/deploy.rst +++ b/content/administration/install/deploy.rst @@ -388,20 +388,112 @@ The solutions to support livechat/motifications in a WSGI application are: with ``/longpolling/`` to :option:`the longpolling port `. -Serving Static Files -==================== +.. _deploy/streaming: -For development convenience, Odoo directly serves all static files in its -modules. This may not be ideal when it comes to performances, and static -files should generally be served by a static HTTP server. +Serving static files and attachments +==================================== -Odoo static files live in each module's ``static/`` folder, so static files -can be served by intercepting all requests to :samp:`/{MODULE}/static/{FILE}`, -and looking up the right module (and file) in the various addons paths. +For development convenience, Odoo directly serves all static files and attachments in its modules. +This may not be ideal when it comes to performances, and static files should generally be served by +a static HTTP server. + +Serving static files +-------------------- + +Odoo static files are located in each module's :file:`static/` folder, so static files can be served +by intercepting all requests to :samp:`/{MODULE}/static/{FILE}`, and looking up the right module +(and file) in the various addons paths. + +.. example:: + Say Odoo has been installed via the **debian packages** for Community and Enterprise, the addons + paths is :file:`/usr/lib/python3/dist-packages/odoo/addons`. Using the above NGINX (https) + configuration, the following location block should be added to serve static files via NGINX. + + .. code-block:: nginx + + location @odoo { + # copy-paste the content of the / location block + } + + # Serve static files right away + location ~ ^/[^/]+/static/.+$ { + root /usr/lib/python3/dist-packages/odoo/addons; + try_files $uri @odoo; + expires 24h; + } + +.. example:: + Say Odoo has been installed via the **source**, and the two git repositories for Community and + Enterprise has been cloned in :file:`/opt/odoo` and :file:`/opt/odoo-enterprise` respectively. + The addons paths is ``/opt/odoo/odoo,/opt/odoo/addons,/opt/odoo-enterprise``. Using the above + NGINX (https) configuragion, the following location block should be added to serve static files + via NGINX. + + .. code-block:: nginx + + location @odoo { + # copy-paste the content of the / location block + } + + # Serve static files right away + location ~ ^/[^/]+/static/.+$ { + try_files /static-base$uri /static-addons$uri /static-enterprise$uri @odoo$uri; + expires 24h; + } + + location /static-base { + internal; + alias /opt/odoo/odoo/addons; + } + + location /static-addons { + internal; + alias /opt/odoo/addons; + } + + location /static-enterprise { + internal; + alias /opt/odoo-enterprise; + } + +.. warning:: + The actual NGINX configuration you need is highly dependent on your own installation. The two + above snippets only highlight two possible configurations and may not be used as-is. + +Serving attachments +------------------- + +Attachments are files stored in the filestore which access is regulated by Odoo. They cannot be +directly accessed via a static web server as accessing them requires multiple lookups in the +database to determine where the files are stored and whether the current user can access them or +not. + +Nevertheless, once the file has been located and the access rights verified by Odoo, it is a good +idea to serve the file using the static web server instead of Odoo. For Odoo to delegate serving +files to the static web server, the `X-Sendfile `_ (apache) or +`X-Accel `_ (nginx) extensions +must be enabled and configured on the static web server. Once it is set up, start Odoo with the +:option:`--x-sendfile ` CLI flag (this unique flag is used for both +X-Sendfile and X-Accel). + + +.. note:: + - The X-Sendfile extension for apache (and compatible web servers) does not require any + supplementary configuration. + - The X-Accel extension for NGINX **does** require the following additionnal configuration: + + .. code-block:: nginx + + location /web/filestore { + internal; + alias /path/to/odoo/data-dir/filestore; + } + + In case you don't know what is the path to your filestore, start Odoo with the + :option:`--x-sendfile ` option and navigate to the ``/web/filestore`` URL + directly via Odoo (don't navigate to the URL via NGINX). This logs a warnings, the message + contains the configuration you need. -.. todo:: test whether it would be interesting to serve filestored attachments - via this, and how (e.g. possibility of mapping ir.attachment id to - filestore hash in the database?) .. _security: diff --git a/content/developer/misc/other/cmdline.rst b/content/developer/misc/other/cmdline.rst index 3567dbf0a..b2f4ea07c 100644 --- a/content/developer/misc/other/cmdline.rst +++ b/content/developer/misc/other/cmdline.rst @@ -430,6 +430,12 @@ HTTP .. warning:: proxy mode *must not* be enabled outside of a reverse proxy scenario +.. option:: --x-sendfile + + delegates serving attachments files to the static web server and sets both + ``X-Sendfile`` (apache) and ``X-Accel-*`` (nginx) http headers on stream + responses. See :ref:`deploy/streaming` for web server configuration. + .. _reference/cmdline/server/logging: Logging