M/01 — Alpenglow module
Transparent S3 reads, writes, and deletes for every Odoo attachment — with automatic local fallback, retry with backoff, and two-phase migration tooling for existing filestores.
01 — Overview
Attachments live in S3. Odoo never notices.
The module overrides three methods on ir.attachment so every read, write, and delete routes through S3. Works with Amazon S3, DigitalOcean Spaces, MinIO, Backblaze B2, and any S3-compatible provider.
If S3 is unreachable or unconfigured, operations fall back to the local filesystem silently — no errors, no downtime, no data loss.
Credentials persist in ir.config_parameter, so they survive Odoo SH builds where environment variables don’t. A production-only mode prevents staging and dev branches from writing to your production bucket.
Purpose-built for Odoo SH instances approaching their storage limit.
02 — What’s included
Three engines, one install.
F/01
S3 storage engine
Transparent read / write / delete that overrides Odoo’s core file methods. Retry up to three times with exponential backoff and jitter before falling back.
Any provider that speaks the S3 API — configurable endpoint and region.
F/02
Odoo SH ready
Credentials in ir.config_parameter persist across builds. Configure from Settings → General Settings → S3 Attachment Storage.
Production-only mode keeps staging and dev branches from mutating your production bucket.
F/03
Migration tooling
Two-phase cron jobs upload every existing attachment to S3, verify with a HEAD request, then delete the local copy.
Batched, resumable, idempotent, deduplicated by checksum.
03 — How it works
Three overrides on ir.attachment. No schema change.
The store_fname field serves double duty as the local path and the S3 object key — no database migration is needed to install or uninstall.
OP/01 — READ
Tries S3 first. If the key doesn’t exist or S3 is unreachable, falls back to the local filesystem.
OP/02 — WRITE
Uploads to S3. On failure, falls back to local storage so the attachment is never lost.
OP/03 — DELETE
Removes the object from S3, then marks any local copy for Odoo’s garbage collector.
04 — Configuration
Four steps. Takes about five minutes.
1. Install boto3
Add boto3 to requirements.txt at the root of your Git repository (not inside the module folder). Odoo SH installs it automatically on each build. For self-hosted, run pip install boto3.
2. Enter S3 credentials
Navigate to Settings → General Settings → S3 Attachment Storage and fill in the five fields below.
| 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. Otherwise 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)
Check Production Only. Staging and dev builds will still read from S3 but will write locally, protecting your production bucket.
4. Migrate existing attachments
Activate the two scheduled actions under Settings → Technical → Scheduled Actions — Phase 1 uploads, Phase 2 verifies and removes local copies. Both are inactive by default.
05 — Supported providers
Any storage that speaks S3.
| 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 |
06 — Compatibility
Odoo 15 – 19. CE & EE. Odoo SH and self-hosted.
| Dependency | Purpose |
|---|---|
| base | Core attachment model and system parameters. |
| base_setup | Settings UI framework. |
| boto3 (pip) | AWS SDK for Python — S3 API client. |
07 — Changelog
What changed and why.
V/17.0.1.0.3
Excluded models, repair action, client caching
- Excluded models for local storage — attachments for
ir.ui.menuandir.ui.viewnow stay on local disk. Menu icons are read on every page load, so round-tripping to S3 was adding noticeable latency. - Repair action — a new scheduled action rehydrates local copies of excluded-model attachments from S3. Useful for existing installations where the cleanup cron already removed them.
- S3 client caching — boto3 clients cached at module scope, keyed on the full credential tuple. Credential rotation handled automatically.
- Simplified read retry — removed the redundant application-level retry loop from
_file_read. Boto3 retries internally; the double loop was amplifying tail latency.
V/17.0.1.0.2
Web assets stored locally
- Excluded mimetypes — CSS, JavaScript, SCSS, and icon files stay on local disk instead of S3. These assets are served on every page load.
- Local-first reads —
_file_readchecks local disk before hitting S3, improving performance for any file with a local copy. - Context-aware writes —
_file_writeroutes business documents to S3 and web assets to local disk. - Migration cron skips assets — Phase 1 now skips web assets and system resources.
V/17.0.1.0.1
S3 garbage collection
- GC cron — a daily scheduled action safely removes orphaned S3 objects. Replaces immediate deletion in
_file_deletewhich could remove shared content-addressed files. - Safe delete deferral —
_file_deletenow defers to the GC cron, which verifies zero references before removing from S3.
V/17.0.1.0.0
Initial release
Transparent S3 attachment storage with automatic fallback, retry with exponential backoff, two-phase migration tooling, Settings UI, production-only mode, and S3-compatible provider support.
08 — Support
A real engineer reads every email.
Email contact@aglow.dev
S3 Attachment Storage is developed and maintained by Alpenglow Technologies LLC. Provided “as is” without warranty of any kind.
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