A Real-Life Guide to Using Odoo.sh: From Creating Your Project to Going Live
Most articles about Odoo.sh explain its features — automated hosting, builds, backups, and deployment.
However, the official documentation mostly focuses on how the platform works. What many developers actually want to understand is how the development and deployment process looks in a real project.
This article explains a typical workflow used by Odoo developers when working with custom modules on Odoo.sh. It also highlights some of the common issues that appear during deployment and how they are usually resolved.
1. Initial Project Setup
The first step is creating a project on Odoo.sh and linking it with a Git repository.
After signing in with a Git provider (GitHub, GitLab, or Bitbucket), the platform automatically creates the project environment and prepares the repository structure.
During this step you normally define:
Project name
Odoo version
Hosting region
Enterprise subscription (if applicable)
A practical recommendation when working with client projects is to host the repository inside the client’s organization account, not a personal developer account. This helps avoid access and ownership issues later.
Once the project is created, the production branch and initial environment are ready.
2. Local Development Workflow
Although Odoo.sh provides a web editor, most development work is done locally.
Developers typically clone the repository and create a separate branch for new features.
Example:
git clone https://github.com/your-org/your-repo.git
cd your-repo
git checkout -b 17.0-feature-inventory
Working with feature branches helps keep the production branch stable and makes it easier to review or revert changes.
Inside the repository, developers add their custom modules or create new ones using the Odoo scaffold command. A typical module includes:
Python models
XML views
security rules
configuration data
If a local Odoo environment is available, testing the module locally before pushing changes can prevent unnecessary build failures later.
3. Pushing Code and Automatic Builds
When code is committed and pushed to the remote repository, Odoo.sh automatically starts a build process.
Example:
git add .
git commit -m "[ADD] custom inventory module"
git push origin 17.0-feature-inventory
The platform detects the push event and prepares a development build. This process installs dependencies, loads the code, and starts the Odoo server.
If the build completes successfully, the branch becomes available as a development environment.
If something goes wrong, the build status turns red and the error details can be found in the build logs.
For developers working with Odoo.sh, reading and understanding build logs is an important part of debugging deployment issues.
4. Testing in Staging
A recommended workflow when working with Odoo.sh is to use three environments:
Development → Staging → Production
After development testing is complete, the branch can be merged into the staging environment.
At this point, Odoo.sh creates a staging instance using a copy of the production database. This allows developers to test new features with real business data.
Typical checks performed in staging include:
verifying that custom views load correctly
testing reports with existing records
validating automated workflows
checking compatibility with existing modules
If issues occur, they only affect the staging environment and production users remain unaffected.
5. Deployment to Production
Once the staging environment has been verified, the changes can be deployed to production.
This usually involves merging the tested branch into the production branch. Odoo.sh automatically updates the server and restarts the Odoo service.
After deployment, developers still need to ensure that Odoo loads the updated module.
The usual steps are:
Enable Developer Mode
Open the Apps menu
Click Update Apps List
Install or upgrade the module
Without this step, the code may exist on the server but the module changes may not yet be applied to the database.
6. Common Issues During Deployment
Even with automated builds, deployment errors are common. Below are some issues frequently encountered in real projects.
Build Failure
A build failure usually means that Odoo could not start.
The build logs typically reveal the cause. In many cases the issue is a Python error such as:
syntax errors
missing imports
indentation mistakes
Once the problem is corrected locally and pushed again, the build process restarts automatically.
Module Not Appearing in Apps
Sometimes a module does not appear in the Apps list even after updating the app list.
This usually means Odoo does not recognize the directory as a valid module.
Check that the module contains the required files:
__manifest__.py
__init__.py
If either file is missing or incorrectly configured, Odoo will ignore the module.
Changes Not Reflected After Upgrade
Developers sometimes push code changes but see no difference after upgrading the module.
A common cause is that the module version was not updated in __manifest__.py.
Updating the version number and upgrading the module again usually resolves this issue.
Missing Python Dependencies
If external Python libraries are used, they must be declared in a requirements.txt file.
For example:
pandas
requests
This file should be placed in the root of the repository. During the next build, Odoo.sh installs these packages automatically.
External ID Errors
Another frequent issue during module installation is an error related to missing external IDs.
This typically occurs when a module inherits views or models from another module but does not declare it as a dependency.
The solution is to update the depends list in the module manifest.
Practical Tips from Real Projects
Some practices help reduce deployment issues when working with Odoo.sh:
Always develop using feature branches
Avoid pushing untested code directly to production
Test features with real data in staging
Check build logs whenever a build fails
Update module versions when modifying data files or views
Following these practices helps maintain a stable deployment workflow.
Conclusion
Odoo.sh simplifies many infrastructure tasks such as server management, backups, and environment setup.
However, successful deployments still depend on disciplined development practices and proper testing.
By following a structured workflow — development, staging, and production — developers can safely deploy custom modules and handle common deployment issues more efficiently.
A failed build is not a disaster. It is simply the platform telling you exactly where the problem is.
Testing with real production data in staging often reveals problems that never appear in a local development environment.