First Odoo Instance
Deploy your first Odoo instance and connect a Git repository
This guide walks you through deploying your first Odoo instance on a connected server. You will create a project, set up an environment, deploy an instance, and optionally connect a Git repository for automated deployments.
Before starting, make sure you have completed the Quick Start guide and have at least one server connected.
Deployment flow overview
Create a project
A project in oCore groups related Odoo instances under a single umbrella. Each project can have multiple environments (development, staging, production), and each environment can have its own instance configuration.
Navigate to projects
In the dashboard, go to Projects in the sidebar, then click Create Project.
Projects Dashboard
View and manage all projects in your organization.
Enter project details
- Name: A descriptive name for the project (e.g., "Client Portal" or "Internal ERP")
- Description (optional): A brief description of what this project is for
Click Create to save the project. You will be taken to the project detail page where you can add environments.
Create an environment
An environment represents a deployment stage within a project. Typical setups include:
| Environment | Purpose | Branch |
|---|---|---|
| Development | Testing and local development | develop |
| Staging | Pre-production testing and QA | staging |
| Production | Live customer-facing instance | main |
Add an environment
On the project detail page, click Add Environment. For your first setup, create a Development environment:
- Name:
Development - Type:
development - Branch (optional): The Git branch this environment deploys from (e.g.,
develop). You can configure this later when connecting a repository.
Select a server
Choose which server the environment's instances will run on. Select the server you added in the Quick Start guide.
Deploy an instance
An instance is a running Odoo container on a server. Each instance has its own database, configuration, and network ports. Learn more about instances in the Concepts section.
Create the instance
Within your environment, click Deploy Instance. Configure the instance:
- Odoo Version: Select the Odoo version (e.g.,
17.0,16.0). oCore supports both Community and Enterprise editions. - Edition:
Community(free) orEnterprise(requires Odoo license) - Workers (optional): Number of Odoo worker processes. Leave as default for development.
oCore allocates network ports automatically. Each instance gets a base port (starting at 10000), with the longpolling port at base+1 and Mailpit at base+2.
Wait for deployment
oCore creates the instance asynchronously. The deployment process includes:
- Pulling the Odoo Docker image on the target server
- Creating the PostgreSQL database for the instance
- Starting the Odoo container with the configured settings
- Running the health check to verify the instance is responding
You can monitor the deployment status in the dashboard. The instance status transitions through:
creating -> running (or failed if something goes wrong).
Access your Odoo instance
Once the instance is running, the dashboard shows the access URL. Click the link to open Odoo in your browser.
On first access, Odoo presents its database initialization wizard. Complete the setup:
- Set the master password
- Create the initial database
- Choose demo data or start fresh
- Set up the admin account
Instances Dashboard
View all running instances, their status, and access URLs.
Connect a Git repository
Connecting a Git repository enables automated deployments. When you push code to the configured branch, oCore automatically deploys the changes to the corresponding environment.
Link the repository
On the project settings page, navigate to the Repository section and click Connect Repository.
Enter:
- Repository URL: The Git clone URL (e.g.,
git@github.com:your-org/your-odoo-modules.git) - Access: oCore uses the SSH gateway or a deploy key to clone the repository
Ensure the oCore server can reach your Git hosting provider (GitHub, GitLab, Bitbucket). If using SSH, the Git host's SSH key must be in the known hosts.
Configure branch mapping
Map Git branches to environments. For example:
develop-> Development environmentstaging-> Staging environmentmain-> Production environment
When code is pushed to a mapped branch, oCore triggers a deployment to the corresponding environment.
Trigger your first deployment
Push a commit to the configured branch, or click Deploy Now in the dashboard to trigger a manual deployment. The deployment process:
- Clones the repository at the configured branch/commit
- Builds the Odoo container with your custom modules
- Takes a pre-deploy snapshot of the database (for rollback)
- Stops the current container and starts the new one
- Runs health checks to verify the deployment succeeded
If the deployment fails, oCore automatically rolls back to the previous version.
Deployments Dashboard
View deployment history, logs, and status for all environments.
Troubleshooting
Instance stuck in "creating" state
If an instance stays in the creating state for more than a few minutes:
- Check the server connection status -- ensure the server is still reachable
- Check the server's Docker daemon is running:
docker pson the target server - Check available disk space -- Odoo Docker images can be several GB
- Review the deployment logs in the dashboard for specific error messages
Cannot access the Odoo instance
If you cannot reach the Odoo instance URL:
- Verify the instance status is
runningin the dashboard - Check that the allocated port is not blocked by a firewall on the target server
- If accessing remotely, ensure the port is forwarded or you have configured a reverse proxy
Deployment fails
Common deployment failure causes:
- Git clone fails: Check repository URL and access credentials
- Build fails: Check for syntax errors in custom modules
- Health check fails: Odoo may need more time to start with large databases. Check instance logs.
- Port conflict: The allocated port may already be in use. oCore auto-assigns ports, but manual conflicts can occur.