Metadata-Version: 2.1
Name: odoo-addon-fs_attachment_s3
Version: 19.0.1.2.0
Requires-Dist: fsspec[s3]
Requires-Dist: odoo-addon-fs_attachment==19.0.*
Requires-Dist: odoo==19.0.*
Summary: Store attachments into S3 complient filesystem
Home-page: https://github.com/OCA/storage
License: AGPL-3
Author: ACSONE SA/NV,Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 19.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

================
Fs Attachment S3
================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:a75c57c5b3d6d0fc0a8450806d17feab5061303aa271f57ad8312986e62314ba
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fstorage-lightgray.png?logo=github
    :target: https://github.com/OCA/storage/tree/19.0/fs_attachment_s3
    :alt: OCA/storage
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/storage-19-0/storage-19-0-fs_attachment_s3
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/storage&target_branch=19.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

This module extends the functionality of
`fs_attachment <https://github.com/OCA/storage/tree/16.0/fs_attachment>`__
to better support Amazon S3 storage. It includes features such as:

- Special handling of X-Accel-Redirect headers for S3 storages.
- Options for using signed URLs in X-Accel-Redirect. (This is required
  to be able to serve files from a private S3 bucket using
  X-Accel-Redirect without exposing the files publicly.)
- Enforcing the mimetype of files stored in S3.

**Table of contents**

.. contents::
   :local:

Configuration
=============

On the Odoo instance, go to *Settings* > *Technical* > *Storage* > *File
Storage*.

When you create a new storage for s3 or modify an existing one, when you
activate the option "Use X-Sendfile To Serve Internal Url", 2 additional
fields will appear:

- **S3 Uses Signed URL For X-Accel-Redirect**: If checked, the
  X-Accel-Redirect path will be a signed URL, which is useful for S3
  storages that require signed URLs for access.
- **S3 Signed URL Expiration**: The expiration time for the signed URL
  in seconds. This field is only relevant if the previous option is
  checked. By default, it is set to 30 seconds but it could be less
  since the url generated into the X-Accel-Redirect process is directly
  used by the web server to serve the file.

The value of these fields can also be set in the server environment
variables using the keys:

- *s3_uses_signed_url_for_x_sendfile*
- *s3_signed_url_expiration*

When the option "Use X-Sendfile To Serve Internal Url" is enabled, the
system will generate an X-Accel-Redirect header in the response to a
request to get a file. In the case of S3 storages, it will follow the
format:

.. code:: text

   X-Accel-Redirect: /fs_x_sendfile/{scheme}/{host}/{path with query if any}

Where:

- ``{scheme}``: The URL scheme (http or https).
- ``{host}``: The host of the S3 storage.
- ``{path with query if any}``: The path to the file in the S3 storage,
  including any query parameters. (Query parameters are set when the
  ``s3_uses_signed_url_for_x_sendfile`` option is enabled.)

In order to serve files using X-Accel-Redirect, you must ensure that
your web server is configured to handle these headers correctly. This
typically involves setting up a location block in your web server
configuration that matches the X-Accel-Redirect path and proxies the
request to the S3 storage.

For example, if you are using Nginx, you would add a location block like
this:

.. code:: nginx


       location ~ ^/fs_x_sendfile/(.*?)/(.*?)/(.*) {
           internal;
           set $url_scheme $1;
           set $url_host $2;
           set $url_path $3;
           set $url $url_scheme://$url_host/$url_path;

           proxy_pass $url$is_args$args;
           proxy_set_header Host $url_host;
           proxy_ssl_server_name on;
        
       }

Unlike the standard implementation of X-Accel-Redirect on non S3
storages, the S3 implementation does not require a base URL to be set in
the storage configuration. The X-Accel-Redirect path is constructed
directly from the S3 storage's URL defined for the connection, the
directory name as bucket name, and the file path.

Changelog
=========

19.0.1.2.0 (2026-03-18)
-----------------------

Features
~~~~~~~~

- Adapt to handle {db_name} in directory_path.
  (`#db_name <https://github.com/OCA/storage/issues/db_name>`__)

18.0.1.2.0 (2025-10-20)
-----------------------

Features
~~~~~~~~

- Adapt to handle {db_name} in directory_path.
  (`#db_name <https://github.com/OCA/storage/issues/db_name>`__)

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/storage/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/storage/issues/new?body=module:%20fs_attachment_s3%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* ACSONE SA/NV

Contributors
------------

- Laurent Mignon laurent.mignon@acsone.eu (https://www.acsone.eu)
- Stéphane Bidoul stephane.bidoul@acsone.eu (https://www.acsone.eu)

Other credits
-------------

The development of this module has been financially supported by:

- ACSONE SA/NV (https://www.acsone.eu)
- Alcyon Belux

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

.. |maintainer-lmignon| image:: https://github.com/lmignon.png?size=40px
    :target: https://github.com/lmignon
    :alt: lmignon

Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:

|maintainer-lmignon| 

This module is part of the `OCA/storage <https://github.com/OCA/storage/tree/19.0/fs_attachment_s3>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
