Projects & Environments
Organizing work with projects, environments, and branch mapping
Projects and environments provide the organizational structure for managing Odoo deployments. A project groups related instances, while environments define deployment stages (development, staging, production) within that project.
Overview
Projects
A project is a logical grouping of environments and their associated instances. Projects typically represent a single Odoo application or client engagement.
When to use projects
| Scenario | Recommended approach |
|---|---|
| Single client with dev/staging/prod | One project with three environments |
| Multiple clients | One project per client |
| Internal ERP + Customer portal | Two separate projects |
| Testing a new Odoo version | New environment within existing project |
Project settings
Each project has:
- Name -- A human-readable name (e.g., "Acme Corp ERP")
- Description -- Optional notes about the project's purpose
- Git repository -- The repository containing custom Odoo modules (optional)
- Default Odoo version -- The default Odoo version for new environments
Environments
An environment defines a deployment stage within a project. Each environment has its own instances, deployment configuration, and optionally its own Git branch.
Standard environment types
While oCore lets you name environments anything you like, following the standard development-staging-production pattern is strongly recommended. It maps naturally to Git branching strategies and deployment pipelines.
| Environment | Purpose | Typical branch | Instance count |
|---|---|---|---|
| Development | Active development and testing | develop | 1 |
| Staging | Pre-production QA and client review | staging | 1 |
| Production | Live customer-facing instances | main | 1+ |
Branch mapping
Each environment can be mapped to a Git branch. When code is pushed to a mapped branch, oCore automatically triggers a deployment to the corresponding environment.
This creates a natural deployment pipeline:
- Developers push to
develop-- changes deploy to Development automatically - When ready, merge
developintostaging-- deploys to Staging for QA - After QA approval, merge
stagingintomain-- deploys to Production
Environment configuration
Each environment can override project-level defaults:
| Setting | Description | Inherited from |
|---|---|---|
| Server | Which server hosts this environment's instances | Must be set per environment |
| Odoo version | Override the project default | Project |
| Git branch | Which branch triggers deployments | Must be set per environment |
| Auto-deploy | Whether Git pushes trigger automatic deployments | Project setting |
The deployment pipeline
When a deployment is triggered (either by a Git push or manually):
- Build -- Clone the repository, build the Docker image with custom modules
- Snapshot -- Take a pre-deploy database snapshot for rollback capability
- Deploy -- Stop the old container, start the new one
- Health check -- Verify the instance is responding correctly
- Complete or rollback -- If health check passes, the deployment is complete. If it fails, restore from the pre-deploy snapshot.
Learn more about the deployment process in Deployments.
Relationship to instances
Each environment can have one or more instances. In most cases, an environment has exactly one instance, but multiple instances are supported for:
- Horizontal scaling -- Running multiple Odoo workers behind a load balancer
- A/B testing -- Running two versions simultaneously
- Blue-green deployments -- Deploying to a standby instance, then switching traffic
Instances inherit their configuration from the environment but can override specific settings (worker count, memory limits, custom modules).
Further reading
- First Instance -- Create a project, environment, and instance step by step
- Deployments -- Deployment process, statuses, and rollback
- Instances -- Instance lifecycle and container management
- Organizations & Teams -- Access control for projects and environments