Create your first project
A project represents one Odoo codebase. It has a Git repo, an Odoo version, and one or more environments (dev, staging, production).
Create the project
- Go to Projects in the sidebar
- Click Create Project
The wizard has two steps:
Step 1: Project info and repository
Project name - Lowercase, hyphens and underscores allowed, 3-50 characters. Examples: acme-erp, client-portal-v2.
Odoo version - Pick the version your codebase targets. This can't be changed after creation.
| Version | Status | Notes |
|---|---|---|
| 18.0 | Stable | Recommended. Supports read replicas. |
| 17.0 | Stable | Battle-tested, long-term support. |
| 19.0 | Beta | Latest features, not production-ready. |
| 16.0 | Legacy | Still works, limited new features. |
| 15.0/14.0 | Deprecated | Not recommended for new projects. |
Git repository - Connect your GitHub or GitLab repo:
- OAuth (recommended): Click "Connect GitHub/GitLab", authorize, and select your repo from the list
- Personal Access Token: Generate a PAT with
repoandadmin:repo_hookscopes, paste it in
You can skip the Git connection and add it later. Without Git, environments deploy with base Odoo only.
Default branch - Usually main or master. Each environment can override this later.
OEC.SH automatically sets up webhooks on your repo so pushing code can trigger deployments. If webhook setup fails (usually a permissions issue), you can configure it manually in project settings.
Step 2: Review and create
Confirm your settings and click Create Project. Takes about a second.
Repository structure
OEC.SH uses official Odoo Docker images and mounts your custom addons on top. Your repo should look something like:
my-repo/
├── addons/ # or put modules at the repo root
│ ├── my_module/
│ │ ├── __init__.py
│ │ ├── __manifest__.py
│ │ └── models/
│ └── another_module/
├── requirements.txt # Python dependencies (optional)
└── apt.txt # System packages (optional)requirements.txt and apt.txt are read at any depth in the repo, so a file inside a module folder (for example addons/my_module/requirements.txt) is installed too. Files under .git, node_modules, .venv and __pycache__ are skipped.
If you need addons from multiple repos (e.g., OCA modules, a themes repo), add them as Addon Repositories in project settings after creation.
What to know about Odoo versions
- Can't change after creation. If you need to upgrade, create a new project with the target version and clone your environment over. Within a version you can freeze the exact build an environment runs.
- Read replicas (Odoo 18.0+ only) aren't available on older versions.
Common issues
"Slug already taken" - Project names must be unique within your organization. Try a more specific name like acme-inventory-erp instead of erp.
"Project quota limit reached" - Your plan limits how many projects you can create. Delete unused projects or upgrade your plan in Settings > Billing.
"Failed to connect to repository" - Your OAuth token or PAT may have expired. Reconnect in Settings > Git Connections.
"Webhook setup failed" - Your token needs admin:repo_hook permissions. You can set up webhooks manually in your Git provider's settings.
Next steps
Your project is ready. Now create an environment to run it:
Deploy your first environment - Create a dev environment and deploy Odoo.