ikus060/openupgrade repository overview

⁠OpenUpgrade Docker

A Docker image to simplify Odoo migration using the open-source OCA/OpenUpgrade⁠ project.

⁠Overview

OpenUpgrade Docker (openupgrade-docker) makes it easier to run upgrade scripts for Odoo instances deployed with Docker. Instead of managing complex migration procedures manually, this project provides a containerized solution that streamlines the entire process.

⁠Disclaimer

• This is an open-source project developed in my free time, based on the work of the Odoo Community Association (OCA) and specifically the OpenUpgrade project.
• This image assumes you are using the official Odoo Docker image for your deployment.

⁠Prerequisites

Before running an upgrade, ensure the following:

1. Set proper permissions on your data folder so it's accessible by the Odoo user (UID=101, GID=101) or (UID=100, GID=101) depending on Odoo version:

   chown -R 101:101 /path/to/odoo/data
   # OR
   chmod -R 755 /path/to/odoo/data
   

   Copy

2. Prepare addons for the target version. Download and place all required addons for the new version in /var/lib/odoo/addons/<VERSION>/ (e.g., /var/lib/odoo/addons/18.0/)

3. Create a database dump (optional, but recommended):

   If you also plan to upgrade your PostgreSQL instance, back up your database as follows. The dump can be used directly by this Docker image to restore your data into your new PostgreSQL server.

   # If PostgreSQL is in Docker and /var/lib/postgresql/data is bind mounted:
   docker exec -it <postgres-container> pg_dump -U odoo -f /var/lib/postgresql/data/<DB_NAME>.sql <DB_NAME>
   
   # If PostgreSQL is local:
   pg_dump -U odoo -f <DB_NAME>.sql <DB_NAME>
   

   Copy

⁠Expected Folder Structure

Your Odoo data directory should be organized as follows:

/var/lib/odoo/                    # Main Odoo data directory (bind mount this)
├── addons/
│   ├── 16.0/                     # Addons for version 16.0
│   │   ├── custom_module_1/
│   │   ├── custom_module_2/
│   │   └── ...
│   ├── 17.0/                     # Addons for version 17.0 (target version)
│   │   ├── custom_module_1/
│   │   ├── custom_module_2/
│   │   └── ...
│   └── 18.0/                     # Addons for version 18.0 (if upgrading further)
│       ├── custom_module_1/
│       ├── custom_module_2/
│       └── ...
├── filestore/
│   └── mydb/                     # Filestore for database 'mydb'
│       └── ...                   # Various attachment files
├── mydb.sql                      # Database dump to migrate (optional)
├── openupgrade-17.0-<DATE>.log   # Log file generated by this docker image
└── sessions/                     # Session data (optional)

Important notes:

• Each version folder under addons/ should contain all your custom modules compatible with that Odoo version
• The filestore/ directory is automatically managed during migration
• Database dumps (.sql files) should be placed in the root of the data directory (only required when using --dump)
• After migration, a new filestore folder will be created (e.g., filestore/mydb_17/)

⁠Usage

⁠Basic Usage

For a standalone PostgreSQL instance:

docker run -it \
  -v /path/to/odoo/data:/var/lib/odoo \
  -e HOST=10.255.4.235 \
  ikus060/openupgrade:17 \
  odoo-openupgrade --db-name mydb --dump mydb.sql --neutralize

Where 10.255.4.235 is your PostgreSQL server address.

⁠Docker Compose / Docker Network

If your PostgreSQL database is part of a Docker Compose setup:

docker run -it \
  -v /srv/odoo/var:/var/lib/odoo \
  -e HOST=<postgres-container> \
  --network <odoo-network> \
  ikus060/openupgrade:17 \
  odoo-openupgrade --db-name mydb --dump mydb.sql

Where:

• <odoo-network> is the network used for your Odoo Docker containers
• <postgres-container> is the PostgreSQL container name

This will upgrade mydb to a new database mydb_17.

⁠Command Options

• --db-name <DB-NAME>: The name of the database to migrate
• --dump <FILENAME>: (Optional) Instead of migrating from an existing database in PostgreSQL, restore the database from this dump file. Very useful if you're also upgrading PostgreSQL
• --neutralize: (Optional) Execute steps to neutralize the database (e.g., disable cron jobs, disable outgoing emails, add web banner, etc.). Enable this when testing your migration

⁠Environment Variables

Configure database connection using these environment variables (similar to the official Odoo image):

⁠Multi-Step Migration

To migrate through multiple versions sequentially, execute the same command with a different target version. It's recommended to test each step to verify your database is working as expected before proceeding to the next version.

# Upgrade to version 17
docker run -it \
  -v /srv/odoo/var:/var/lib/odoo \
  -e HOST=<postgres-container> \
  --network <odoo-network> \
  ikus060/openupgrade:17 \
  odoo-openupgrade --db-name mydb --dump mydb.sql

# Then upgrade to version 18
docker run -it \
  -v /srv/odoo/var:/var/lib/odoo \
  -e HOST=<postgres-container> \
  --network <odoo-network> \
  ikus060/openupgrade:18 \
  odoo-openupgrade --db-name mydb_17

⁠After Migration

Once the migration completes successfully, a new database get created named <DB-NAME>_99 where 99 is you target odoo version. A new file store is also created matching your database name.

Official Odoo image:

docker run -d \
  -v /path/to/odoo/data:/var/lib/odoo \
  -e HOST=<postgres-container> \
  -p 8069:8069 \
  odoo:17

Or this OpenUpgrade image (which is based on the official image):

docker run -d \
  -v /path/to/odoo/data:/var/lib/odoo \
  -e HOST=<postgres-container> \
  -p 8069:8069 \
  ikus060/openupgrade:17 \
  odoo

⁠Troubleshooting

⁠Migration Process

• The migration process may fail for various reasons. Always review the logs carefully (e.g., openupgrade-17.0-<DATE>.log)
• Look for ERROR messages first, then examine any WARNING messages
• You can run the same command multiple times. The script will drop and recreate the database and filestore on each run

⁠Common Issues

• Permission errors: Ensure your data folder has correct permissions (UID=101, GID=101) or (UID=100, GID=101)
• Missing addons: Verify all required addons are present in the correct version folder
• Database connection: Check that environment variables match your PostgreSQL configuration
• Network issues: If using Docker networks, ensure the container is attached to the correct network

⁠Feedback and Contributions

• OpenUpgrade Docker issues: Please open an issue at openupgrade-docker⁠
• OpenUpgrade migration issues: Report directly to OCA/OpenUpgrade⁠

⁠License

This project follows the same license as OCA/OpenUpgrade. Please refer to the OpenUpgrade project⁠ for license details.

⁠Acknowledgments

This project is built upon the excellent work of:

• Odoo Community Association (OCA)⁠
• OpenUpgrade Project⁠
• The official Odoo Docker image