S3 Attachment Storage
Store Odoo file attachments in Amazon S3 or any S3-compatible
object storage — with automatic fallback, retry logic, and migration tooling.
☁ S3 & S3-Compatible 🔄 Automatic Fallback 📦 Migration Tooling
ⓘ Description
S3 Attachment Storage transparently redirects all Odoo file attachment reads, writes, and deletes to an S3 bucket. It works with Amazon S3, DigitalOcean Spaces, MinIO, Backblaze B2, and any other S3-compatible provider.
If S3 is unreachable or unconfigured, every operation falls back to the local filesystem silently — no errors, no downtime. The module includes two-phase migration tooling to upload your existing filestore to S3 and reclaim local disk space, making it ideal for Odoo SH instances approaching their storage limit.
|
☁
Transparent StorageAll attachment operations route through S3 automatically — no workflow changes for users |
🔄
Resilient FallbackAutomatic retry with exponential backoff, then seamless fallback to local storage on failure |
📦
Migration ToolingTwo-phase cron jobs upload existing attachments to S3 and then clean up local copies safely |
⚙ Key Features
S3 Storage Engine
- Transparent Read / Write / Delete — overrides Odoo’s core
ir.attachmentfile methods so all attachments route through S3 automatically - S3-Compatible Providers — works with any provider that speaks the S3 API: Amazon S3, DigitalOcean Spaces, MinIO, Backblaze B2, and more
- Configurable Endpoint & Region — set a custom endpoint URL and region code for non-AWS providers
- Retry with Backoff — all S3 operations retry up to 3 times with exponential backoff and jitter before falling back
- Automatic Local Fallback — if S3 is unreachable or credentials are missing, operations fall back to the local filesystem silently
Odoo SH Ready
- Database-Stored Credentials — credentials are saved in
ir.config_parameterand persist across Odoo SH builds (environment variables do not) - Settings UI — configure everything from Settings → General Settings → S3 Attachment Storage
- Production-Only Mode — staging and dev builds read from S3 but write locally, preventing non-production builds from modifying your production bucket
- Environment Variable Fallback — for self-hosted deployments, credentials can also be set via environment variables
Migration Tooling
- Phase 1: Upload to S3 — a scheduled action reads each local attachment and uploads it to S3 in configurable batches
- Phase 2: Cleanup Local Files — verifies each file exists in S3 (via HEAD request), then deletes the local copy to reclaim disk space
- Batch Processing — configurable batch size (default 100) with progress tracking via system parameters
- Safe & Resumable — progress is committed between batches, respects worker time limits, and resumes automatically on the next cron cycle
- Idempotent — safe to re-run after interruption; duplicate uploads overwrite with the same content, duplicate cleanups are no-ops
- Deduplication — skips redundant uploads when multiple attachment records share the same file (Odoo deduplicates by checksum)
⚡ How It Works
The module overrides three core methods on ir.attachment.
The store_fname field serves as both the local path and the S3 object key — no database migration is needed.
|
R
|
Read — tries S3 first. If the key doesn’t exist or S3 is unreachable, falls back to the local filesystem. |
|
W
|
Write — uploads to S3. On failure, falls back to local storage so the attachment is never lost. |
|
D
|
Delete — removes the object from S3, then marks the local file for Odoo’s garbage collector (in case it also exists locally). |
🔧 Configuration
1. Install boto3
Add boto3 to the
requirements.txt at the
root of your Git repository (not inside the module folder). On Odoo SH, this is installed
automatically on each build. On self-hosted, run
pip install boto3.
2. Enter S3 Credentials
Navigate to Settings → General Settings → S3 Attachment Storage and fill in:
| Field | Description |
|---|---|
| S3 Bucket | Bucket or Space name |
| Access Key ID | AWS access key or provider equivalent |
| Secret Access Key | AWS secret key or provider equivalent (masked in UI) |
| Endpoint URL | Leave empty for AWS S3. For other providers, set the endpoint (e.g. https://nyc3.digitaloceanspaces.com) |
| Region | AWS region code (e.g. us-east-1) or provider region |
3. Enable Production-Only Mode (Odoo SH)
If you are on Odoo SH, enable the Production Only checkbox. This prevents staging and dev builds from writing to or deleting from your production S3 bucket. Those builds can still read from S3, so migrated attachments remain accessible.
4. You’re Ready
All new attachments will now be stored in S3. Existing attachments remain on the local filesystem until you run the migration (see below).
On Odoo SH, environment variables do not persist across builds. Always use the Settings UI to store credentials.
🚀 Migrating Existing Attachments
Two scheduled actions under Settings → Technical → Scheduled Actions handle migration in two phases. Both are inactive by default and must be activated manually.
Phase 1: Upload to S3Reads each binary attachment from the local filesystem and uploads it to S3 in batches. Skips duplicates automatically. Runs every 2 minutes until complete. |
Phase 2: Cleanup Local FilesVerifies each attachment exists in S3, then deletes the local copy to reclaim disk space. Will not run unless Phase 1 is complete. |
Test on a staging branch first. Set
s3_attachment.migration_max_id as a system parameter to limit the scope of a dry run.
🌐 Supported Providers
Works with any storage provider that implements the S3 API:
| Provider | Endpoint URL |
|---|---|
| Amazon S3 | (leave empty) |
| DigitalOcean Spaces | https://nyc3.digitaloceanspaces.com |
| MinIO | http://minio.internal:9000 |
| Backblaze B2 | https://s3.us-west-002.backblazeb2.com |
📦 Dependencies
This module requires the following:
| Dependency | Purpose |
|---|---|
Base base |
Core attachment model and system parameters |
Base Setup base_setup |
Settings UI framework |
boto3 pip |
AWS SDK for Python — S3 API client |
🎙 Support
Questions or issues? We're here to help.
✉ contact@aglow.dev
S3 Attachment Storage is developed and maintained by Alpenglow Technologies LLC.
This software is provided "as is", without warranty of any kind, express or implied.
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module