Transparent ir.attachment override - _file_read/write/delete routes through S3 automatically

S3-compatible providers - AWS, DO Spaces, MinIO, B2, Wasabi, any S3 API

Settings UI - all configuration in Settings -> General Settings with Test Connection button

Automatic local fallback - if S3 is unreachable, writes go to local filesystem silently

Retry with exponential backoff + jitter - boto3 adaptive retry mode (3 attempts)

Production-only mode - staging/dev builds read from S3 but write locally

Two-phase migration cron - Phase 1 uploads, Phase 2 verifies + cleans up local copies

S3 garbage collection cron - daily, removes orphaned S3 objects with double-check safety

Repair action - weekly, rehydrates local copies of excluded-model attachments from S3

Excluded models and mimetypes - web assets stay local, fully configurable

Migration progress dashboard - smart button showing total/uploaded/pending/failed counts

Encryption support - SSE-S3 (default) and SSE-KMS options

Health check endpoint - JSON endpoint showing S3 connection status

CLI verification tool - standalone script to test S3 connectivity outside Odoo

Uninstall safety - S3 objects remain intact on uninstall

Installation & Setup

1. Install the module: Go to Apps -> Search for "oe_s3_attachment_storage" -> Click Install
2. Install the boto3 Python package: pip install boto3
3. Configure permissions: Navigate to Settings -> Technical -> S3 Attachment Storage to grant access to administrators who will manage S3 configuration

Basic Usage

1. Configure S3: Go to Settings -> General Settings -> S3 Attachment Storage section and enter your bucket name, access key ID, and secret access key
2. Test connection: Click "Test Connection" to verify your S3 credentials and bucket access
3. Run migration: Open the S3 Migration Dashboard and click "Run Phase 1" to upload existing attachments in batches
4. Verify and clean: After Phase 1 completes, click "Run Phase 2" to verify uploads and clean up local copies

Tips & Best Practices

• Start with dry-run mode to preview what migration and GC crons will do before running them live
• Use production-only mode in staging environments to read from S3 without writing to it
• Configure excluded models and mimetypes to keep web assets (CSS, JS, icons) on local disk for performance
• Set a path prefix for multi-environment buckets to keep production, staging, and dev data separate

Important Notes

The boto3 Python package is required. Install it via pip before using the module. For production deployments, configure IAM roles or restricted access keys with minimal S3 permissions. S3 objects remain intact on uninstall - no data loss. Always test with dry-run mode first before running live migration or GC operations.

Q: Which S3-compatible storage providers are supported?

A: ``oe_s3_attachment_storage`` works with any S3-compatible provider including AWS S3, DigitalOcean Spaces, MinIO, Backblaze B2, Wasabi, and any other service that implements the S3 API. Configure the endpoint URL in Settings for non-AWS providers.

Q: Does this module require changes to existing Odoo code or database schema?

A: No. The module overrides ir.attachment internal methods transparently. No schema changes, no model modifications, and no code changes are needed. Existing attachments are migrated via the two-phase migration cron.

Q: What happens if S3 is temporarily unreachable?

A: The module automatically falls back to local filesystem storage with exponential backoff and jitter (3 retry attempts). Writes succeed locally, and no errors are raised. Once S3 is available again, the GC cron can clean up any local-only files.

Q: Is this module safe for production use on Odoo.sh?

A: Yes. The module auto-detects Odoo.sh environments and includes production-only mode. Staging and development builds read from S3 but write locally, preventing accidental data contamination. The two-phase migration ensures data integrity.

Why Choose Odoo Engineering