Create Your First Project

Learn how to create your first Odoo project on OEC.SH, connect your Git repository, and configure Odoo version settings.

What is a Project?

A project in OEC.SH represents a single Odoo application container with its codebase, configuration, and environments. Think of it as:

• One Odoo Codebase: Your custom Odoo application with its addons and modules
• Multiple Environments: Development, staging, and production instances of the same codebase
• Git-Connected: Linked to your GitHub/GitLab repository for continuous deployment
• Version-Locked: Uses a specific Odoo version (17.0, 18.0, 19.0, etc.)

Key Characteristics:

• Projects belong to an organization (your team workspace)
• Each project can have unlimited environments
• Environments can be deployed to different servers
• All environments share the same Odoo version and codebase

Prerequisites

Before creating your first project, ensure you have:

• ✅ Organization created (GST-002: Create Account)
• ✅ Server added (GST-003: Add Server)
• ✅ Storage configured (GST-004: Storage Setup)
• ✅ Git repository (GitHub or GitLab, public or private)
• ✅ Odoo custom addons (optional, can be added later)

Create Project Wizard

┌─────────────────────────────────────┐
│ Organization *                      │
│ ┌─────────────────────────────────┐ │
│ │ 🏢 Acme Corporation          ▼ │ │
│ └─────────────────────────────────┘ │
│ Current projects: 2 / 10 (20%)      │
└─────────────────────────────────────┘

❌ Project Quota Limit Reached
You have reached your organization's project limit.
Current projects: 10 / 10
Please contact your administrator to increase quota limits.

Project Name *
┌─────────────────────────────────────┐
│ my-odoo-erp                         │
└─────────────────────────────────────┘

Description
┌─────────────────────────────────────┐
│ Customer-facing ERP portal with     │
│ custom inventory management module  │
└─────────────────────────────────────┘

Odoo Version *
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│ 19.0 │ │ 18.0 │ │ 17.0 │ │ 16.0 │
│      │ │ [✓]  │ │      │ │      │
│ Beta │ │Default││      │ │      │
└──────┘ └──────┘ └──────┘ └──────┘

┌─────────────────────────────────────────┐
│ 🚀 Creating from Odoo.sh Migration     │
│                                         │
│ 📦 Odoo 17.0                           │
│ 💾 production-backup-2024-12-10        │
│                                         │
│ ✅ Odoo version locked for compatibility│
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ 🔗 Skip Repository Connection           │
│                                          │
│ Create project without a Git repository. │
│ You can connect one later.               │
└─────────────────────────────────────────┘

Git Connection
┌─────────────────────────────────────┐
│ 🔗 GitHub - john@example.com     ▼ │
└─────────────────────────────────────┘

Search repositories
┌─────────────────────────────────────┐
│ 🔍 Search...                        │
└─────────────────────────────────────┘

Your Repositories
┌─────────────────────────────────────┐
│ 📦 acme-corp/odoo-custom            │
│    🔒 Private • Updated 2 hours ago │
├─────────────────────────────────────┤
│ 📦 acme-corp/erp-addons             │
│    🌍 Public • Updated 1 day ago    │
└─────────────────────────────────────┘

Default Branch
┌─────────────────────────────────────┐
│ 🌿 main                          ▼ │
└─────────────────────────────────────┘

Available Branches:
• main (default)
• develop
• feature/v18-migration
• hotfix/invoice-bug

✅ Webhook Configuration
┌─────────────────────────────────────┐
│ Webhook URL:                        │
│ https://api.oec.sh/webhooks/github  │
│                                     │
│ Events:                             │
│ • Push events                       │
│ • Pull request merged               │
│                                     │
│ Status: ✅ Active                   │
└─────────────────────────────────────┘

⚠️ Webhook setup failed
Failed to register webhook automatically.
You can manually configure webhooks in Project Settings.

┌─────────────────────────────────────┐
│ 🖥️  Infrastructure Configuration    │
│                                     │
│ You can configure VM and environment│
│ settings after project creation.    │
│                                     │
│ Default Configuration:              │
│ ✅ Production & Staging environments│
│ ✅ Automatic SSL certificates       │
│ ✅ Daily backups (7-day retention)  │
│ ✅ Resource monitoring              │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ 📋 Review Your Project              │
│                                     │
│ Organization                        │
│ Acme Corporation                    │
│                                     │
│ Project Name                        │
│ my-odoo-erp                         │
│                                     │
│ Odoo Version                        │
│ 18.0                                │
│                                     │
│ Repository                          │
│ acme-corp/odoo-custom (github)      │
│                                     │
│ Default Branch                      │
│ main                                │
└─────────────────────────────────────┘

Repository: acme-corp/odoo-custom (github)
Default branch: main

[← Previous]  [✓ Create Project]

Project Created Successfully

After clicking "Create Project", you'll see a success message and be redirected to your project dashboard:

┌─────────────────────────────────────┐
│ ✅ Project Created Successfully     │
│                                     │
│ my-odoo-erp is now ready for        │
│ deployment.                         │
│                                     │
│ Next: Create your first environment │
└─────────────────────────────────────┘

Project Dashboard Overview

Your project dashboard shows:

Header Section:

my-odoo-erp                           [⚙️ Settings] [🗑️ Delete]
Odoo 18.0 • Created 2 minutes ago
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quick Stats:

┌──────────────┬──────────────┬──────────────┐
│ Environments │ Deployments  │ Last Deploy  │
│      0       │      0       │     Never    │
└──────────────┴──────────────┴──────────────┘

Tabs:

• Overview: Project stats, recent activity
• Environments: List of environments (empty for new projects)
• Deployments: Deployment history
• Repository: Git settings, branches, commits
• Settings: Project configuration

Project Status Lifecycle

Your project progresses through these statuses:

Next Steps

Now that your project is created, follow these steps:

# Navigate to Environments tab
Project → Environments → Create Environment

Production Environment
┌─────────────────────────────────────┐
│ System URL (auto-generated)         │
│ https://my-odoo-erp-prod.oec.sh     │
│                                     │
│ Custom Domain                       │
│ erp.acme-corp.com                   │
└─────────────────────────────────────┘

Backup Policy
• Daily at 2:00 AM UTC
• Retention: 7 days
• Storage: Cloudflare R2

# Project Settings → Members
Email: developer@acme-corp.com
Role: Developer

Git Repository Configuration

Repository Structure

OEC.SH expects your Odoo repository to follow this structure:

my-odoo-repo/
├── addons/                    # Your custom addons
│   ├── my_custom_module/
│   │   ├── __init__.py
│   │   ├── __manifest__.py
│   │   ├── models/
│   │   ├── views/
│   │   └── security/
│   └── another_module/
├── requirements.txt           # Python dependencies (optional)
├── odoo.conf                  # Odoo configuration (optional)
└── README.md

Supported Repository Layouts

Option 1: Addons Only (Recommended)

repo-root/
└── addons/              ← Mounted to /mnt/extra-addons
    ├── module_1/
    ├── module_2/
    └── module_3/

Option 2: Odoo Full

repo-root/
├── odoo/                ← Odoo core (ignored by OEC.SH)
├── addons/              ← Your custom addons (used)
└── enterprise/          ← Enterprise addons (optional)

Option 3: Multiple Addon Directories

repo-root/
├── custom/              ← Primary addons directory
├── third_party/         ← Additional repo (add via Addon Repos)
└── themes/              ← Additional repo (add via Addon Repos)

Branch Strategy Best Practices

Recommended Git Flow:

main (production)
  ↑
develop (staging)
  ↑
feature/* (development)

Environment-Branch Mapping:

Example workflow:

1. Developer creates feature branch: feature/new-inventory
2. Push triggers auto-deploy to dev environment
3. Merge to develop → auto-deploys to staging
4. After testing, merge to main → manual deploy to production

Webhook Events

OEC.SH webhooks respond to these Git events:

GitHub Events:

• push - Code pushed to branch
• pull_request - PR opened, synchronized, reopened, closed
• release - Release published (for tagged deployments)

GitLab Events:

• Push Hook - Code pushed to branch
• Merge Request Hook - MR merged
• Tag Push Hook - Tag created

Auto-Deploy Logic:

if event == "push" and branch == environment.git_branch:
    if environment.auto_deploy == True:
        trigger_deployment(environment)

Odoo Version Details

Version Comparison

Docker Image Selection

By default, OEC.SH uses official Odoo Docker images:

# Default images
odoo:19.0   # Odoo 19.0 Community
odoo:18.0   # Odoo 18.0 Community
odoo:17.0   # Odoo 17.0 Community
odoo:16.0   # Odoo 16.0 Community

Enterprise Images: If you have an Odoo Enterprise license, configure custom images:

Project Settings → Docker Image
┌─────────────────────────────────────┐
│ Image Source: Docker Hub Private    │
│ Image Name: mycompany/odoo-enterprise│
│ Tag: 18.0                           │
│ Registry Credentials: [Configure]    │
└─────────────────────────────────────┘

Version Migration Strategy

Upgrading Odoo versions requires creating a new project:

1. Create new project with target Odoo version
2. Clone production environment from old project
3. Run upgrade scripts in new environment
4. Test thoroughly in staging
5. DNS cutover when ready
6. Archive old project

Troubleshooting

Git Connection Failed

Error Message:

❌ Failed to connect to repository
Could not access repository 'acme-corp/odoo-custom'

Common Causes:

1. Invalid OAuth Token

   • Solution: Reconnect OAuth in Settings → Git Connections
   • Revoke and re-authorize access

2. PAT Expired

   • Solution: Generate new PAT with same scopes
   • Update in Settings → Git Connections

3. Repository Deleted or Renamed

   • Solution: Update repository URL in project settings
   • Verify repository exists in Git provider

4. Insufficient Permissions

   • Solution: Ensure PAT/OAuth has repo and admin:repo_hook scopes
   • For organization repos, verify you're an admin

Debug Steps:

# Test connection manually
curl -H "Authorization: token YOUR_PAT" \
  https://api.github.com/repos/OWNER/REPO
 
# Expected: 200 OK with repository JSON

Repository Not Found

Error Message:

❌ Repository not found
The repository 'acme-corp/odoo-custom' does not exist or you don't have access.

Solutions:

1. Check Repository Exists

   • Verify URL in GitHub/GitLab
   • Ensure repository name is correct (case-sensitive)

2. Verify Access Permissions

   • You must have at least read access
   • For webhooks, need admin access

3. Organization Permissions

   • If repo is in an organization, authorize organization access
   • GitHub: Settings → Applications → OEC.SH → Grant organization access

Webhook Setup Failed

Error Message:

⚠️ Webhook setup failed
Failed to register webhook automatically.
You can manually configure webhooks in Project Settings.

Common Causes:

1. Insufficient Permissions

   • Required: admin:repo_hook scope (GitHub) or Maintainer role (GitLab)
   • Solution: Re-authorize with correct scopes

2. Repository Archived

   • Solution: Unarchive repository before creating webhooks

3. Webhook Already Exists

   • Solution: Delete existing webhook in Git provider
   • OEC.SH will create a new one

Manual Webhook Setup:

# GitHub Webhook Configuration
Payload URL: https://api.oec.sh/api/v1/webhooks/github
Content type: application/json
Secret: [Copy from Project Settings]
Events:
  ✓ Push events
  ✓ Pull requests
SSL: Enable SSL verification

Slug Already Taken

Error Message:

❌ Project slug 'my-odoo-erp' is already taken
Please choose a different project name.

Solution:

• Project slugs must be unique within your organization
• Try adding a suffix: my-odoo-erp-v2, my-odoo-erp-2024
• Or use a more specific name: acme-inventory-erp

Quota Limit Reached

Error Message:

❌ Project Quota Limit Reached
You have reached your organization's project limit.
Current projects: 10 / 10
Please contact your administrator to increase quota limits.

Solutions:

1. Delete Unused Projects

   • Archive or delete projects you no longer need
   • Quota is freed immediately

2. Upgrade Plan

   • Free: 1 project
   • Starter: 5 projects
   • Professional: 10 projects
   • Business: 25 projects
   • Enterprise: Unlimited projects

3. Request Quota Increase

   • Enterprise customers can request custom quotas
   • Contact support@oec.sh

Invalid Odoo Version

Error Message:

❌ Odoo version 19.0 is not available
Version 19.0 is in beta and disabled for this organization.

Solution:

• Beta versions may be restricted by organization settings
• Contact organization admin to enable beta versions
• Or choose a stable version (17.0, 18.0)

API Reference

Create Project

Create a new project via API.

Endpoint: POST /api/v1/projects

Authentication: Bearer token required

Permission: org.projects.create

Request Body:

{
  "name": "my-odoo-erp",
  "description": "Customer-facing ERP portal",
  "odoo_version": "18.0",
  "repository_url": "https://github.com/acme-corp/odoo-custom.git",
  "repository_provider": "github",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000"
}

Request Schema:

interface ProjectCreate {
  name: string;                    // 3-50 characters, alphanumeric + hyphens
  slug?: string;                   // Auto-generated if not provided
  description?: string;            // Optional, max 200 characters
  odoo_version: "14.0" | "15.0" | "16.0" | "17.0" | "18.0" | "19.0";
  repository_url?: string;         // Git clone URL
  repository_provider?: "github" | "gitlab";
  organization_id?: string;        // UUID, uses default org if not provided
  image_config?: {                 // Optional custom Docker image
    source_type: "docker_hub" | "docker_hub_private" | "aws_ecr" | "gcp_gcr" | "azure_acr" | "gitlab_registry" | "github_registry" | "self_hosted";
    image_name: string;            // e.g., "odoo" or "mycompany/odoo-custom"
    image_tag?: string;            // e.g., "18.0", defaults to odoo_version
    registry_url?: string;         // For private registries
    registry_credentials_id?: string; // UUID of stored credentials
  };
}

Response: 201 Created

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-odoo-erp",
  "slug": "my-odoo-erp",
  "description": "Customer-facing ERP portal",
  "odoo_version": "18.0",
  "organization_id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_name": "Acme Corporation",
  "repository_url": "https://github.com/acme-corp/odoo-custom.git",
  "repository_provider": "github",
  "status": "pending",
  "webhook_secret": "whsec_abc123...",
  "webhook_id": "123456789",
  "created_at": "2024-12-11T10:30:00Z",
  "updated_at": "2024-12-11T10:30:00Z"
}

cURL Example:

curl -X POST https://api.oec.sh/api/v1/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-odoo-erp",
    "description": "Customer-facing ERP portal",
    "odoo_version": "18.0",
    "repository_url": "https://github.com/acme-corp/odoo-custom.git",
    "repository_provider": "github"
  }'

Error Responses:

// 400 Bad Request - Validation Error
{
  "detail": "Name must be at least 3 characters"
}
 
// 403 Forbidden - Quota Exceeded
{
  "detail": "Project quota limit reached. Current: 10/10"
}
 
// 403 Forbidden - Permission Denied
{
  "detail": "Missing required permission: org.projects.create"
}
 
// 409 Conflict - Slug Taken
{
  "detail": "Project slug 'my-odoo-erp' already exists in this organization"
}

Get Project

Retrieve project details.

Endpoint: GET /api/v1/projects/{project_id}

cURL Example:

curl https://api.oec.sh/api/v1/projects/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Project

Update project settings.

Endpoint: PATCH /api/v1/projects/{project_id}

Request Body:

{
  "description": "Updated description",
  "repository_url": "https://github.com/acme-corp/new-repo.git"
}

Note: name, slug, odoo_version, and organization_id cannot be changed after creation.

Delete Project

Delete a project and all its environments.

Endpoint: DELETE /api/v1/projects/{project_id}

cURL Example:

curl -X DELETE https://api.oec.sh/api/v1/projects/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Warning: This action:

• Deletes all environments and their data
• Stops all running containers
• Removes all backups (unless stored externally)
• Cannot be undone

Best Practices

Project Naming

✅ Good Names:

• acme-erp-production
• client-portal-v2
• inventory-management-2024

❌ Bad Names:

• test (too generic)
• My Project (has spaces)
• project123 (not descriptive)

Repository Organization

Monorepo Strategy (Multiple addons in one repo):

odoo-custom/
├── addons/
│   ├── inventory_module/
│   ├── sales_customization/
│   └── reporting_dashboard/
└── requirements.txt

Multi-Repo Strategy (Separate addon repos):

Project: my-erp
├── Primary Repo: core-addons
└── Additional Repos:
    ├── inventory-addons
    ├── sales-addons
    └── third-party-addons

Version Selection

Decision Matrix:

Quota Management

Monitor usage regularly:

Settings → Usage
━━━━━━━━━━━━━━━━━━━
Projects: ████████░░ 8/10 (80%)
Environments: ███░░░░░░░ 15/50 (30%)
CPU: ████████░░ 16/20 cores (80%)
RAM: ████████░░ 32/40 GB (80%)

Optimize resource usage:

• Delete unused environments
• Consolidate similar projects
• Archive old projects
• Upgrade plan if consistently near limits

Related Documentation

• GST-006: Deploy Your First Environment - Next step after project creation
• Projects Overview - Complete project management guide
• Git Integration - Advanced Git workflows
• Addon Management - Managing multiple addon repositories
• Custom Docker Images - Using custom Odoo images
• Webhook Configuration - Manual webhook setup
• Permission System - Understanding RBAC permissions
• API Reference - Complete API documentation

Support

Need help creating your first project?

• 📖 Documentation: https://docs.oec.sh (opens in a new tab)
• 💬 Community Forum: https://community.oec.sh (opens in a new tab)
• 📧 Email Support: support@oec.sh
• 💼 Enterprise Support: Available on Business and Enterprise plans

Common questions:

• How do I change the Odoo version? (You can't - create new project)
• Can I use Odoo Enterprise? (Yes, configure custom image)
• How many projects can I create? (Depends on your plan)
• Can I connect multiple Git repos? (Yes, via Addon Repositories)

Last Updated: December 11, 2024 (Sprint 2E42 - Phase 1)